Andal.LND/edx-platform
6
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Fix formatting on interapp APIs extension ADR.

Browse Source 
The numbered lists were not written correctly.
This commit is contained in:
David Ormsbee
2021-01-22 15:59:22 -05:00
parent 669677c78a
commit d531d38ec7
2 changed files with 30 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/decisions/0002-inter-app-apis.rst
View File

@@ -9,27 +9,36 @@ Accepted
Context
=======
The edx-platform Django project is a conglomeration of different LMS and Studio features written in the structure of Django apps. Over the years, the boundaries between features have become muddled for various reasons. We now find apps intruding into the Python innards of other apps, making the intrusive apps tightly dependent on the inner behaviors of other apps.
The edx-platform Django project is a conglomeration of different LMS and Studio
features written in the structure of Django apps. Over the years, the boundaries
between features have become muddled for various reasons. We now find apps
intruding into the Python innards of other apps, making the intrusive apps
tightly dependent on the inner behaviors of other apps.
Due to this lack of clearly delimited separation of concerns, the monolith has become hard to maneuver, comprehend, and modify.
Due to this lack of clearly delimited separation of concerns, the monolith has
become hard to maneuver, comprehend, and modify.
Decisions
=========
#. Each Django app should clearly define a set of Python APIs that it exposes to other Django apps, which run within the LMS/Studio process.
#. Each app's Python APIs should be defined/exported in a Python module called "api.py", located in the top-most directory of the app.
#. The app's Python APIs should be well-named, self-consistent, and relevant to its own "domain" (without exposing technical and implementation details).
#. An app's Django models and other internal data structures should not be exposed via its Python APIs.
#. Ideally, tests should use only Python APIs declared in other apps' "api.py" files. However, if an app's API is needed only for testing (and not needed as part of the app's domain API), then test-relevant Python APIs should be defined/exported in an intentional Python module called "api_for_tests.py".
1. Each Django app should clearly define a set of Python APIs that it exposes to
other Django apps, which run within the LMS/Studio process.
2. Each app's Python APIs should be defined/exported in a Python module called
"api.py", located in the top-most directory of the app.
3. The app's Python APIs should be well-named, self-consistent, and relevant to
its own "domain" (without exposing technical and implementation details).
4. An app's Django models and other internal data structures should not be
exposed via its Python APIs.
5. Ideally, tests should use only Python APIs declared in other apps' "api.py"
files. However, if an app's API is needed only for testing (and not needed as
part of the app's domain API), then test-relevant Python APIs should be
defined/exported in an intentional Python module called "api_for_tests.py".
Exmaples
~~~~~~~~
As a reference example, see the Python APIs exposed by the grades app in the `grades/api.py module`_.
As a reference example, see the Python APIs exposed by the grades app in the
`grades/api.py module`_.
.. _`grades/api.py module`: https://github.com/edx/edx-platform/blob/master/lms/djangoapps/grades/api.py
@@ -37,8 +46,12 @@ As a reference example, see the Python APIs exposed by the grades app in the `gr
Consequences
============
#. Explicitly defining Python APIs will prevent the proliferation of unintended entanglement between apps in the monolith.
#. When developers invest time in carefully considering Python APIs, they will need to consider good SOLID design practices for abstractions and encapsulation, leading to cleaner and more comprehensible code.
#. Python clients outside of an app will interface only through declared APIs in either "api.py" or "test_api.py". The provider app therefore has better control and oversight to support its intentional APIs.
1. Explicitly defining Python APIs will prevent the proliferation of unintended
entanglement between apps in the monolith.
2. When developers invest time in carefully considering Python APIs, they will
need to consider good SOLID design practices for abstractions and
encapsulation, leading to cleaner and more comprehensible code.
3. Python clients outside of an app will interface only through declared APIs in
either "api.py" or "test_api.py" (or exported via an api/__init__.py). The
provider app therefore has better control and oversight to support its
intentional APIs.

8
openedx/core/djangoapps/content/learning_sequences/docs/decisions/0001-extensions-to-inter-app-apis.rst
View File

@@ -33,25 +33,19 @@ Decision
#. All API data structures will be declared as immutable attrs classes in a
separate ``data.py`` file. All data class attributes will have type annotations.
#. Data structures in ``data.py`` will include basic validation of their inputs,
though this will *not* include validation that requires database access.
#. All public inter-app API functions will use type annotations for arguments
and return values.
#. All public inter-app API functions will be exported in the top level ``api``
package. Other applications will only ever import from this top level package.
#. Views, tasks, and any other parts of the learning_sequences app that are not
in the api package will obey the same rules that external apps would follow.
This means that views for learning_sequences will only import from api and will
not directly import from models.
#. Serializers for REST APIs will be defined as inner classes on the views.
Serializer re-use across use cases will be explicitly discouraged to prevent
modifications from rippling across and breaking compatibility elsewhere.
#. Wherever possible, API-level tests will be written without mocking internals,
or prepping the database with model manipulations. The goal of this is to make
it so that that API-level tests *only* break when there are in fact API changes.
@@ -63,10 +57,8 @@ Consequences
#. It will be easier for other applications to access learning_sequence
functionality in a more easily understood and maintainable way.
#. It will be easier to build and maintain plugin code that depends on this
application.
#. Changes that break backwards compatibility will be more obvious.