From a0865bc10d205fdaead830e9bef0fb9d39a4e62c Mon Sep 17 00:00:00 2001 From: Jesper Hodge Date: Mon, 27 Nov 2023 14:21:49 -0500 Subject: [PATCH] docs: improve explanations --- .../0003-hybrid-approach-for-public-apis.rst | 7 ++---- ...4-service-layer-for-contentstore-views.rst | 25 ++++++++++++++----- 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/cms/djangoapps/contentstore/docs/decisions/0003-hybrid-approach-for-public-apis.rst b/cms/djangoapps/contentstore/docs/decisions/0003-hybrid-approach-for-public-apis.rst index ced1533e65f8..4efb932fb77f 100644 --- a/cms/djangoapps/contentstore/docs/decisions/0003-hybrid-approach-for-public-apis.rst +++ b/cms/djangoapps/contentstore/docs/decisions/0003-hybrid-approach-for-public-apis.rst @@ -10,11 +10,8 @@ Reason for rejection -------------------- The objectives for public authoring APIs changed from the time this decision was made: -we are now implementing a limited set of experimental APIs that are intended as an -MVP for a future, more complete set of APIs. The authoring APIs we are implementing -are a public set of wrappers around existing functionality, and are not intended to -be used for production course authoring yet. The responsibility for avoiding conflicts -and resolving them if they occur is on the user. +We are now limiting our offering to a set of experimental APIs with which to flesh our what a supported set of APIs might become. As such, the authoring APIs we are now implementing +are just a public set of wrappers around existing functionality, and are not fit for production course authoring. The responsibility for avoiding conflicts and resolving them, if they occur, is on the user. Context ------- diff --git a/cms/djangoapps/contentstore/docs/decisions/0004-service-layer-for-contentstore-views.rst b/cms/djangoapps/contentstore/docs/decisions/0004-service-layer-for-contentstore-views.rst index aafd0e9c96b7..17b56f41d2f4 100644 --- a/cms/djangoapps/contentstore/docs/decisions/0004-service-layer-for-contentstore-views.rst +++ b/cms/djangoapps/contentstore/docs/decisions/0004-service-layer-for-contentstore-views.rst @@ -31,8 +31,21 @@ Consequences ------------ - Future view methods should confine business logic to the service layer. This ADR mandates the extraction of business logic from view files into separate entities, without prescribing specific file structures or naming conventions. -Examples --------- +Example +------- + +The following example shows a refactoring to this service layer pattern. + +Before refactoring, the view method implements some view-related logic like +authorization via `if not has_studio_read_access: ...` and serialization, +but also business logic: instantiating modulestore, fetching videos from it, +and then transforming the data to generate a new data structure `usage_locations`. + +After refactoring, the view method only implements logic related to the view / API layer, +and the business logic is extracted to a service file called `videos_provider.py` outside +the `views` folder. Now the videos provider is responsible for fetching and transforming +the data, while the view is responsible for authorization and serialization. + **Before:**:: @@ -50,10 +63,10 @@ Examples store = modulestore() usage_locations = [] videos = store.get_items( - course_key, - qualifiers={ - 'category': 'video' - }, + course_key, + qualifiers={ + 'category': 'video' + }, ) for video in videos: video_id = getattr(video, 'edx_video_id', '')