diff --git a/openapi/components/examples/curriculumFolderUsage-list.yaml b/openapi/components/examples/curriculumFolderUsage-list.yaml new file mode 100644 index 00000000..2fb90aa1 --- /dev/null +++ b/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 diff --git a/openapi/components/examples/curriculumFolderUsage-tree.yaml b/openapi/components/examples/curriculumFolderUsage-tree.yaml new file mode 100644 index 00000000..610d087d --- /dev/null +++ b/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 diff --git a/openapi/components/parameters/curriculum-ancestors.yaml b/openapi/components/parameters/curriculum-ancestors.yaml new file mode 100644 index 00000000..6f1e188f --- /dev/null +++ b/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 diff --git a/openapi/components/parameters/curriculum-descendants.yaml b/openapi/components/parameters/curriculum-descendants.yaml new file mode 100644 index 00000000..ed0d5709 --- /dev/null +++ b/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 diff --git a/openapi/components/parameters/curriculum-folderId.yaml b/openapi/components/parameters/curriculum-folderId.yaml new file mode 100644 index 00000000..53960b45 --- /dev/null +++ b/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 diff --git a/openapi/components/parameters/curriculum-returnFormat.yaml b/openapi/components/parameters/curriculum-returnFormat.yaml new file mode 100644 index 00000000..374cb059 --- /dev/null +++ b/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 diff --git a/openapi/components/responses/curriculumFolderUsage-list.yaml b/openapi/components/responses/curriculumFolderUsage-list.yaml new file mode 100644 index 00000000..7469d163 --- /dev/null +++ b/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 diff --git a/openapi/components/schemas/curriculumItem.yaml b/openapi/components/schemas/curriculumItem.yaml index 8ecb92da..b55c4d17 100644 --- a/openapi/components/schemas/curriculumItem.yaml +++ b/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 \ No newline at end of file + example: GCPSC-SEA + children: + description: | + Optional list of child nodes of this curriculum node. + type: array + items: + $ref: ./curriculumItem.yaml diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index b93167dc..4a4e3e68 100644 --- a/openapi/openapi.yaml +++ b/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/api@search.yaml' diff --git a/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@folder@{folderId}.yaml new file mode 100644 index 00000000..10ae68fc --- /dev/null +++ b/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 diff --git a/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml b/openapi/paths/api@curriculum@usage@{id}@folder@{folderId}.yaml new file mode 100644 index 00000000..6cfb50ed --- /dev/null +++ b/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