From 185e6c2d768ec88e9b59fa7cc8720afda36d3516 Mon Sep 17 00:00:00 2001 From: David Ormsbee Date: Wed, 3 Feb 2021 08:13:25 -0500 Subject: [PATCH] fix: RST formatting for APIs ADR. (#26336) --- .../content/learning_sequences/README.rst | 2 +- .../0001-extensions-to-inter-app-apis.rst | 50 ++++++++++--------- 2 files changed, 27 insertions(+), 25 deletions(-) diff --git a/openedx/core/djangoapps/content/learning_sequences/README.rst b/openedx/core/djangoapps/content/learning_sequences/README.rst index 2855f73fe8..0f03a16367 100644 --- a/openedx/core/djangoapps/content/learning_sequences/README.rst +++ b/openedx/core/djangoapps/content/learning_sequences/README.rst @@ -88,4 +88,4 @@ I want to pull data from ModuleStore or Block Structures. Making any synchronous calls to these systems will break the performance goals of this app. If you need data from these systems, please find a way to push that -data into smaller mdoels at course publish time. +data into smaller models at course publish time. diff --git a/openedx/core/djangoapps/content/learning_sequences/docs/decisions/0001-extensions-to-inter-app-apis.rst b/openedx/core/djangoapps/content/learning_sequences/docs/decisions/0001-extensions-to-inter-app-apis.rst index 2df63ccb4b..fa8ca089fd 100644 --- a/openedx/core/djangoapps/content/learning_sequences/docs/decisions/0001-extensions-to-inter-app-apis.rst +++ b/openedx/core/djangoapps/content/learning_sequences/docs/decisions/0001-extensions-to-inter-app-apis.rst @@ -31,35 +31,37 @@ to the existing set of Inter-app APIs defined at the top level of edx-platform. 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. -We can mock calls to other services, like grades. +1. 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. +2. Data structures in ``data.py`` will include basic validation of their inputs, + though this will *not* include validation that requires database access. +3. All public inter-app API functions will use type annotations for arguments + and return values. +4. 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. +5. 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. +6. 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. +7. 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. We can mock calls to other services, like grades. 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. +1. It will be easier for other applications to access learning_sequence + functionality in a more easily understood and maintainable way. +2. It will be easier to build and maintain plugin code that depends on this + application. +3. Changes that break backwards compatibility will be more obvious. References