Curriculum node add/remove to/from folder API docs [SA-17416]

openapi/components/examples/curriculumFolderUsage-list.yaml

@@ -0,0 +1,7 @@
+value:
+  - id: 100
+    name: Self-awareness
+    code: GCPSC-SEA
+  - id: 200
+    name: Self-discipline
+    code: GCPSC-SED

openapi/components/examples/curriculumFolderUsage-tree.yaml

@@ -0,0 +1,20 @@
+value:
+  - id: 1
+    name: Traits
+    children:
+    - id: 100
+      name: Self-awareness
+      code: GCPSC-SEA
+      children:
+        - id: 101
+          name: Test 1
+        - id: 102
+          name: Test 2
+    - id: 200
+      name: Self-discipline
+      code: GCPSC-SED
+      children:
+        - id: 201
+          name: Test 1
+        - id: 202
+          name: Test 2

openapi/components/parameters/curriculum-ancestors.yaml

@@ -0,0 +1,11 @@
+name: ancestors
+in: query
+description: |
+  The number of levels of ancestry to retrieve, if this endpoint is
+  returning a tree.
+schema:
+  type: integer
+  format: int32
+  minimum: 0
+  maximum: 50
+  default: 50

openapi/components/parameters/curriculum-descendants.yaml

@@ -0,0 +1,11 @@
+name: descendants
+in: query
+description: |
+  The number of levels of descendants to retrieve, if this endpoint is
+  returning a tree.
+schema:
+  type: integer
+  format: int32
+  minimum: 0
+  maximum: 50
+  default: 50

openapi/components/parameters/curriculum-folderId.yaml

@@ -0,0 +1,9 @@
+name: folderId
+in: path
+description: |
+  The ID of the folder to modify curriculum nodes for.
+required: true
+schema:
+  type: integer
+  format: int32
+  minimum: 1

openapi/components/parameters/curriculum-returnFormat.yaml

@@ -0,0 +1,19 @@
+name: returnFormat
+in: query
+description: |
+  The format to return the folder's curriculum nodes in.
+  * tree: return a response containing the below relations, reduced to a single
+    tree structure:
+    * all top-level curriculum nodes which are ancestors of the folder's nodes
+      (up to `ancestors` levels up)
+    * the folder's actual curriculum nodes
+    * all descendants of the folder's curriculum nodes
+      (up to `descendants` levels down)
+  * list: return a response containing only the folder's curriculum nodes, in a
+    flat structure
+schema:
+  type: string
+  enum:
+    - tree
+    - list
+  default: list

openapi/components/responses/curriculumFolderUsage-list.yaml

@@ -0,0 +1,16 @@
+description: |
+  The new list of curriculum nodes for this folder.
+
+  If parameter `returnFormat` is `tree`, then this will return a tree
+  beginning from the topmost node; otherwise it will return an empty list.
+content:
+  application/json:
+    schema:
+      type: array
+      items:
+        $ref: ../schemas/curriculumItem.yaml
+    examples:
+      list:
+        $ref: ../examples/curriculumFolderUsage-list.yaml
+      tree:
+        $ref: ../examples/curriculumFolderUsage-tree.yaml

openapi/components/schemas/curriculumItem.yaml

@@ -1,5 +1,5 @@
 title: a Curriculum Code
-description: A Curriculm Code
+description: A Curriculum Code
 readOnly: true
 type: object
 properties:
@@ -10,4 +10,10 @@ properties:
     example: Self-awareness
   code:
     type: string
-    example: GCPSC-SEA
+    example: GCPSC-SEA
+  children:
+    description: |
+      Optional list of child nodes of this curriculum node.
+    type: array
+    items:
+      $ref: ./curriculumItem.yaml

openapi/openapi.yaml

@@ -241,6 +241,12 @@ paths:
   /api/curriculum/usage/{id}:
     $ref: 'paths/api@curriculum@usage@{id}.yaml'
 
+  /api/curriculum/usage/{id}/folder/{folderId}:
+    $ref: 'paths/api@curriculum@usage@{id}@folder@{folderId}.yaml'
+
+  /api/curriculum/usage/folder/{folderId}:
+    $ref: 'paths/api@curriculum@usage@folder@{folderId}.yaml'
+
   /api/search:
     $ref: 'paths/[email protected]'
 

openapi/paths/api@curriculum@usage@folder@{folderId}.yaml

@@ -0,0 +1,37 @@
+post:
+  operationId: curriculumApiUsageFolder.postFolderUsage
+  tags: [curriculum]
+  summary: Set curriculum nodes associated with a folder
+  description: |
+    Set the curriculum nodes associated with a folder.
+
+    Returns a 200 response with the new structure the nodes were set,
+    or a 404 if any node to be added was not found.
+  requestBody:
+    content:
+      application/json:
+        schema:
+          description: |
+            An array of curriculum nodes to associate with the folder.
+
+            This will override the folder's current association completely: any
+            nodes not in this list will be disassociated from the folder.
+            (If this is empty, the folder will have no nodes associated.)
+
+          type: array
+          items:
+            $ref: ../components/schemas/curriculumItem.yaml
+
+  responses:
+    '200':
+      $ref: ../components/responses/curriculumFolderUsage-list.yaml
+    '404':
+      description: One or more curriculum nodes to be added were not found.
+    default:
+      $ref: ../components/responses/problem.yaml
+
+parameters:
+  - $ref: ../components/parameters/curriculum-folderId.yaml
+  - $ref: ../components/parameters/curriculum-ancestors.yaml
+  - $ref: ../components/parameters/curriculum-descendants.yaml
+  - $ref: ../components/parameters/curriculum-returnFormat.yaml

openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml

@@ -0,0 +1,40 @@
+post:
+  operationId: curriculumApiUsageFolder.postSingleFolderUsage
+  tags: [curriculum]
+  summary: Add curriculum node to a folder
+  description: |
+    Add a single curriculum node to a folder.
+
+    Returns a 200 response with the new structure if the node was added,
+    or a 409 if it was already on the folder.
+  responses:
+    '200':
+      $ref: ../components/responses/curriculumFolderUsage-list.yaml
+    '409':
+      description: The curriculum node already exists on the folder.
+    default:
+      $ref: ../components/responses/problem.yaml
+
+delete:
+  operationId: curriculumApiUsageFolder.deleteSingleFolderUsage
+  tags: [curriculum]
+  summary: Remove curriculum node from a folder
+  description: |
+    Remove a single curriculum node from a folder.
+
+    Returns a 200 response with the new structure if the node was removed,
+    or a 404 if it did not already exist on the folder.
+  responses:
+    '200':
+      $ref: ../components/responses/curriculumFolderUsage-list.yaml
+    '404':
+      description: The curriculum node does not exist on the folder.
+    default:
+      $ref: ../components/responses/problem.yaml
+
+parameters:
+  - $ref: ../components/parameters/id.yaml
+  - $ref: ../components/parameters/curriculum-folderId.yaml
+  - $ref: ../components/parameters/curriculum-ancestors.yaml
+  - $ref: ../components/parameters/curriculum-descendants.yaml
+  - $ref: ../components/parameters/curriculum-returnFormat.yaml