Merge pull request #2258 from openedx/sameen/add-doc-policy-allocate

feat: document policy allocate endpoint
openedx · May 22, 2024 · ef7ca9e · ef7ca9e
2 parents 2d6d11e + 0201179
commit ef7ca9e
Showing 1 changed file with 173 additions and 58 deletions.
diff --git a/en_us/enterprise_api/source/api_reference/reference.rst b/en_us/enterprise_api/source/api_reference/reference.rst
@@ -16,6 +16,15 @@ Endpoints
 
 The following endpoints are available in the Enterprise API.
 
+- **/policy-allocation/{policy_uuid}/allocate/** - You can make POST calls to the
+  ``/enterprise/v1/policy-allocation/{policy_uuid}/allocate/`` endpoint to allocate
+  an assignment in the requested SubsidyAccessPolicy record to a list of users.
+  For details, see :ref:`policy_allocation Endpoint`.
+
+- **/assignment-configurations-cancel** - You can make POST calls to the
+  ``enterprise/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/`` to cancel the learner content assignment.
+  For details, see :ref:`assignment-configurations-cancel Endpoint`.
+
 - **/subscriptions** - You can make GET calls to the
   ``/enterprise/v1/subscriptions`` endpoint to get a list of subscription plans.
   For details, see :ref:`subscriptions_summary Endpoint`.
@@ -64,9 +73,6 @@ The following endpoints are available in the Enterprise API.
   enterprise learners and their status in the courses they are enrolled in.
   For details, see :ref:`learner_summary Endpoint`.
 
-- **/assignment-configurations-cancel** - You can make POST calls to the
-  ``enterprise/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/`` to cancel the learner content assignment.
-  For details, see :ref:`assignment-configurations-cancel Endpoint`.
 
   `Use this JSON file <https://raw.githubusercontent.com/openedx/edx-documentation/master/en_us/enterprise_api/source/api_reference/edX_Enterprise_API_Reference%20Collection.postman_collection.json>`_ to import into your `Postman enviroment <https://learning.postman.com/docs/getting-started/importing-and-exporting-data/>`_ . It includes the endpoints mentioned above.
 
@@ -89,6 +95,169 @@ example, to request JSON-formatted information about a course run using
    -H "Authorization: JWT {access token}"
    -H "Accept: application/json"
 
+.. _Policy_allocation Endpoint:
+
+**************************
+policy-allocation Endpoint
+**************************
+
+POST calls to the ``policy-allocation`` endpoint to allocate an assignment to a list of users provided in the request body in the requested content_key.
+
+===================
+Method and Endpoint
+===================
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Method
+     - Endpoint
+   * - POST
+     - ``/enterprise/v1/policy-allocation/{policy_uuid}/allocate/``
+
+==============
+Request Values
+==============
+The ``POST /enterprise/v1/policy-allocation/{policy_uuid}/allocate/`` request accepts the following values in the body of the request:
+
+.. list-table::
+   :widths: 25 20 80
+   :header-rows: 1
+
+   * - Field
+     - Data Type
+     - Description
+   * - ``learner_emails``
+     - array
+     - Learner emails to whom assignment should be allocated.
+   * - ``content_key``
+     - string
+     - Course content_key to which these learners are assigned.
+   * - ``content_price_cents``
+     - integer
+     - The price, in USD cents, of this content at the time of allocation. Must be >= 0.
+
+===============
+Example Request
+===============
+::
+
+   curl -X POST
+     https://api.edx.org/enterprise/v1/policy-allocation/904b1785-9d3a-1000-848d-6ae7a56e6355/allocate/ \
+     -H 'Authorization: JWT {access token}'
+     -H 'Content-Type: application/json' \
+     -d '{"learner_emails":["abc@example.com","xyz@example.com"],"content_key":"edx+api101","content_price_cents":1000}'
+
+===============
+Response Values
+===============
+The ``/enterprise/v1/policy-allocation/{policy_uuid}/allocate/`` request returns the following response values:
+
+.. list-table::
+   :widths: 25 20 80
+   :header-rows: 1
+
+   * - Field
+     - Data Type
+     - Description
+   * - ``updated``
+     - integer
+     - Assignment records whose state was transitioned to "allocated" as a result of this action.
+   * - ``created``
+     - integer
+     - New assignment records that were created as a result of this action.
+   * - ``no_change``
+     - array
+     - Already-allocated assignment records related to the requested policy, learner email(s), and content for this action.
+
+===================
+Example Response
+===================
+
+A sample response with a status `202 Accepted` will look like:
+
+::
+
+   {
+        "updated": [],
+        "created": [
+            {
+                "uuid": "4fa11bd53f29c131aa72",
+                "assignment_configuration": "6fc7ef56e6eb209f7668",
+                "learner_email": "abc@example.com",
+                "lms_user_id": 123123,
+                "content_key": "edx+101",
+                "content_title": "edX 101",
+                "content_quantity": -10000,
+                "state": "allocated",
+                "transaction_uuid": null,
+                "actions": [],
+                "earliest_possible_expiration": {
+                    "date": "2024-08-20T11:58:34.666249Z",
+                    "reason": "NINETY_DAYS_PASSED"
+                }
+            }
+        ],
+        "no_change": []
+   }
+
+.. _Assignment-configurations-cancel Endpoint:
+
+*************************************************************************************
+/assignment-configurations-cancel  Endpoint
+*************************************************************************************
+
+POST calls to the ``/assignment-configurations-cancel`` to cancel content assignments of learners.
+
+===================
+Method and Endpoint
+===================
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Method
+     - Endpoint
+   * - POST
+     - ``enterprise/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/``
+
+=====================
+Request Values
+=====================
+The ``POST enterprise/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/`` request accepts the following values in the body of the request:
+
+.. list-table::
+   :widths: 25 20 80
+   :header-rows: 1
+
+   * - Field
+     - Data Type
+     - Description
+   * - ``assignment_uuids``
+     - array
+     - List of assignment UUIDs for the learners that need to be canceled, associated with the assignment configuration UUID specified in the URL.
+
+=====================
+Example Request
+=====================
+
+Request payload
+::
+
+   curl -X POST
+     https://api.edx.org/enterprise/v1/assignment-configurations/6fc7ef56-d1c4-4aa8-a649-e6eb209f0000/admin/assignments/cancel/ \
+     -H 'Authorization: JWT {access token}'
+     -H 'Content-Type: application/json' \
+     -d '{"assignment_uuids":["8977ef56-d1c4-4aa8-a649-e6eb209f0000","8907ef56-d1c4-4aa8-a649-e6eb209f0000"]'
+
+===================
+Example Response
+===================
+
+A sample response with a status `200 OK` will be returned
+
 .. _Subscriptions_summary Endpoint:
 
 **********************
@@ -286,6 +455,7 @@ A sample response with a status `200 OK` will look like:
     ]
    }
 
+
 .. _Licenses_assign Endpoint:
 
 ************************
@@ -545,61 +715,6 @@ A sample response with a status `201 Created` will look like:
     "job_id": "<UUID4>"
    }
 
-.. _Assignment-configurations-cancel Endpoint:
-
-*************************************************************************************
-/assignment-configurations-cancel  Endpoint
-*************************************************************************************
-
-POST calls to the ``/assignment-configurations-cancel`` to cancel content assignments of learners.
-
-===================
-Method and Endpoint
-===================
-
-.. list-table::
-   :widths: 20 80
-   :header-rows: 1
-
-   * - Method
-     - Endpoint
-   * - POST
-     - ``enterprise/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/``
-
-=====================
-Request Values
-=====================
-The ``POST enterprise/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/`` request accepts the following values in the body of the request:
-
-.. list-table::
-   :widths: 25 20 80
-   :header-rows: 1
-
-   * - Field
-     - Data Type
-     - Description
-   * - ``assignment_uuids``
-     - array
-     - List of assignment UUIDs for the learners that need to be canceled, associated with the assignment configuration UUID specified in the URL.
-
-=====================
-Example Request
-=====================
-
-Request payload
-::
-
-   curl -X POST
-     https://api.edx.org/enterprise/v1/assignment-configurations/6fc7ef56-d1c4-4aa8-a649-e6eb209f0000/admin/assignments/cancel/ \
-     -H 'Authorization: JWT {access token}'
-     -H 'Content-Type: application/json' \
-     -d '{"assignment_uuids":["8977ef56-d1c4-4aa8-a649-e6eb209f0000","8907ef56-d1c4-4aa8-a649-e6eb209f0000"]'
-
-===================
-Example Response
-===================
-
-A sample response with a status `200 OK` will be returned
 
 .. _Enterprise_catalogs Endpoint: