[ENG-11427] 1.9.1 BE: Update API documentation

swagger-spec/cedar_metadata/definition.yaml

@@ -45,7 +45,7 @@ definitions:
         properties:
           self:
             type: string
-            example: https://api.osf.io/v2/_/cedar_metadata_records/record-abc123/
+            example: https://api.osf.io/_/cedar_metadata_records/record-abc123/
           metadata_download:
             type: string
-            example: https://api.osf.io/v2/_/cedar_metadata_records/record-abc123/metadata_download/
+            example: https://api.osf.io/_/cedar_metadata_records/record-abc123/metadata_download/

swagger-spec/cedar_metadata/files_list.yaml

@@ -35,4 +35,6 @@ post:
       description: You do not have permission to create metadata for this file.
     '404':
       description: File not found.
+    '405':
+      description: Returned if creating CEDAR metadata records for this file has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
 

swagger-spec/cedar_metadata/nodes_list.yaml

@@ -35,4 +35,6 @@ post:
       description: You do not have permission to create metadata for this node.
     '404':
       description: Node not found.
+    '405':
+      description: Returned if creating CEDAR metadata records for this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
 

swagger-spec/cedar_metadata/record_detail.yaml

@@ -0,0 +1,176 @@
+get:
+  summary: Retrieve a CEDAR metadata record
+  description: >
+    Retrieve a single CEDAR metadata record by its ID.
+
+
+    **Note:** This is a private, unversioned endpoint. Its full URL is
+    `https://api.osf.io/_/cedar_metadata_records/{record_id}/` and does not include the `/v2/`
+    prefix used by the rest of the API, even though it is nested under `/v2/` in this documentation
+    for tooling reasons.
+  operationId: getCedarMetadataRecord
+  tags:
+    - CEDAR Metadata
+  produces:
+    - application/vnd.api+json
+  parameters:
+    - name: record_id
+      in: path
+      description: The unique identifier of the CEDAR metadata record.
+      required: true
+      type: string
+  responses:
+    '200':
+      description: Successfully retrieved the CEDAR metadata record.
+      schema:
+        $ref: './definition.yaml#/definitions/CedarMetadataRecord'
+    '401':
+      description: Authentication credentials were not provided or are invalid.
+    '403':
+      description: You do not have permission to view this CEDAR metadata record.
+    '404':
+      description: CEDAR metadata record not found.
+
+patch:
+  summary: Update a CEDAR metadata record
+  description: >
+    Update the `metadata` and/or `is_published` fields of an existing CEDAR metadata record.
+    Only the fields included in the request are changed.
+  operationId: updateCedarMetadataRecord
+  tags:
+    - CEDAR Metadata
+  consumes:
+    - application/vnd.api+json
+  produces:
+    - application/vnd.api+json
+  parameters:
+    - name: record_id
+      in: path
+      description: The unique identifier of the CEDAR metadata record.
+      required: true
+      type: string
+    - in: body
+      name: body
+      description: CEDAR metadata record fields to update.
+      required: true
+      schema:
+        type: object
+        properties:
+          data:
+            type: object
+            properties:
+              id:
+                type: string
+                example: record-abc123
+              type:
+                type: string
+                example: cedar-metadata-records
+              attributes:
+                type: object
+                properties:
+                  metadata:
+                    type: object
+                    example:
+                      title: Updated Title
+                  is_published:
+                    type: boolean
+                    example: true
+  responses:
+    '200':
+      description: Successfully updated the CEDAR metadata record.
+      schema:
+        $ref: './definition.yaml#/definitions/CedarMetadataRecord'
+    '400':
+      description: Validation error or invalid data.
+    '401':
+      description: Authentication credentials were not provided or are invalid.
+    '403':
+      description: You do not have permission to update this CEDAR metadata record.
+    '404':
+      description: CEDAR metadata record not found.
+    '405':
+      description: Returned if write access to this CEDAR metadata record has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
+
+put:
+  summary: Replace a CEDAR metadata record
+  description: >
+    Replace the `metadata` and/or `is_published` fields of an existing CEDAR metadata record.
+    Behaves the same as `PATCH` on this endpoint.
+  operationId: replaceCedarMetadataRecord
+  tags:
+    - CEDAR Metadata
+  consumes:
+    - application/vnd.api+json
+  produces:
+    - application/vnd.api+json
+  parameters:
+    - name: record_id
+      in: path
+      description: The unique identifier of the CEDAR metadata record.
+      required: true
+      type: string
+    - in: body
+      name: body
+      description: CEDAR metadata record fields to update.
+      required: true
+      schema:
+        type: object
+        properties:
+          data:
+            type: object
+            properties:
+              id:
+                type: string
+                example: record-abc123
+              type:
+                type: string
+                example: cedar-metadata-records
+              attributes:
+                type: object
+                properties:
+                  metadata:
+                    type: object
+                    example:
+                      title: Updated Title
+                  is_published:
+                    type: boolean
+                    example: true
+  responses:
+    '200':
+      description: Successfully updated the CEDAR metadata record.
+      schema:
+        $ref: './definition.yaml#/definitions/CedarMetadataRecord'
+    '400':
+      description: Validation error or invalid data.
+    '401':
+      description: Authentication credentials were not provided or are invalid.
+    '403':
+      description: You do not have permission to update this CEDAR metadata record.
+    '404':
+      description: CEDAR metadata record not found.
+    '405':
+      description: Returned if write access to this CEDAR metadata record has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
+
+delete:
+  summary: Delete a CEDAR metadata record
+  description: >
+    Permanently delete a CEDAR metadata record. Unlike `PATCH`/`PUT`, this action is not blocked
+    by the write restriction described below.
+  operationId: deleteCedarMetadataRecord
+  tags:
+    - CEDAR Metadata
+  parameters:
+    - name: record_id
+      in: path
+      description: The unique identifier of the CEDAR metadata record.
+      required: true
+      type: string
+  responses:
+    '204':
+      description: Successfully deleted the CEDAR metadata record.
+    '401':
+      description: Authentication credentials were not provided or are invalid.
+    '403':
+      description: You do not have permission to delete this CEDAR metadata record.
+    '404':
+      description: CEDAR metadata record not found.

swagger-spec/collections/collected_metadata_list.yaml

@@ -326,3 +326,5 @@ post:
   responses:
     '201':
       description: 'OK'
+    '405':
+      description: 'Returned if new submissions to this collection are currently restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."'

swagger-spec/custom_metadata/nodes_list.yaml

@@ -55,4 +55,6 @@ patch:
     '403':
       description: You do not have permission to modify this metadata record.
     '404':
-      description: Metadata record not found.
+      description: Metadata record not found.
+    '405':
+      description: Returned if write access to the referenced project has been restricted (this restriction does not apply to metadata records associated with files). The response will include the message "This action is no longer available. Contact support if you have any questions."

swagger-spec/nodes/contributor_detail.yaml

@@ -126,6 +126,9 @@ patch:
     If the given user is not already in the contributor list, a 404 Not Found error will be returned.
     A node must always have at least one admin, and any attempt to downgrade the permissions of a sole admin will result in a 400 Bad Request error.
 
+    Some common error cases:
+     - `405 Method Not Allowed`: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
+
   parameters:
     - in: path
       type: string
@@ -151,6 +154,8 @@ patch:
   responses:
     '200':
       description: 'OK'
+    '405':
+      description: 'Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."'
 
 delete:
   summary: Delete a contributor
@@ -173,6 +178,9 @@ delete:
     If the request is unsuccessful, a JSON object with an `errors` key containing information about the failure will be returned.
     Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request may have failed.
 
+    Some common error cases:
+     - `405 Method Not Allowed`: If write access to this node has been restricted, a contributor removing themselves is still permitted, but attempting to remove a different contributor will return this error with the message "This action is no longer available. Contact support if you have any questions."
+
   parameters:
     - in: path
       type: string
@@ -190,3 +198,5 @@ delete:
   responses:
     '204':
       description: 'No content'
+    '405':
+      description: 'If write access to this node has been restricted, a contributor removing themselves is still permitted, but attempting to remove a different contributor will return this error with the message "This action is no longer available. Contact support if you have any questions."'

swagger-spec/nodes/contributors_list.yaml

@@ -148,6 +148,9 @@ post:
     If the request is unsuccessful, an `errors` key containing information about the failure will be returned.
     Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request may have failed.
 
+    Some common error cases:
+     - `405 Method Not Allowed`: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
+
   parameters:
     - in: path
       type: string
@@ -168,3 +171,5 @@ post:
   responses:
     '201':
       description: 'Success'
+    '405':
+      description: 'Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."'

swagger-spec/nodes/detail.yaml

@@ -183,6 +183,9 @@ patch:
     If the request is unsuccessful, an `errors` key containing information about the failure will be returned.
     Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request may have failed.
 
+    Some common error cases:
+     - `405 Method Not Allowed`: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
+
   parameters:
     - in: path
       type: string
@@ -214,6 +217,8 @@ patch:
   responses:
     '200':
       description: 'OK'
+    '405':
+      description: 'Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."'
 
 delete:
   summary: Delete a node

swagger-spec/nodes/draft_registrations_list.yaml

@@ -173,3 +173,5 @@ post:
  responses:
    '201':
      description: 'Created'
+   '405':
+     description: 'Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."'

swagger-spec/nodes/identifiers_list.yaml

@@ -182,3 +182,6 @@ post:
 
     '404':
       description: Node not found. Verify the node ID is correct and that you have permission to view the node.
+
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."

swagger-spec/nodes/node_settings_list.yaml

@@ -206,3 +206,5 @@ patch:
       description: Forbidden. You do not have permission to modify node settings.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."

swagger-spec/nodes/relationships_institutions_list.yaml

@@ -143,6 +143,8 @@ patch:
       description: Forbidden. You do not have permission to modify institutions for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
 
 post:
   summary: Add relationships between a Node and Institutions
@@ -229,6 +231,8 @@ post:
       description: Forbidden. You do not have permission to modify institutions for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
 
 delete:
   summary: Remove relationships between a Node and Institutions
@@ -294,3 +298,5 @@ delete:
       description: Forbidden. You do not have permission to modify institutions for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."

swagger-spec/nodes/relationships_linked_nodes_list.yaml

@@ -164,6 +164,8 @@ patch:
       description: Forbidden. You do not have permission to modify linked nodes for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
 
 post:
   summary: Add relationships between a Node and linked Nodes
@@ -252,6 +254,8 @@ post:
       description: Forbidden. You do not have permission to modify linked nodes for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
 
 delete:
   summary: Remove relationships between a Node and linked Nodes
@@ -317,3 +321,5 @@ delete:
       description: Forbidden. You do not have permission to modify linked nodes for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."

swagger-spec/nodes/relationships_linked_registrations_list.yaml

@@ -164,6 +164,8 @@ patch:
       description: Forbidden. You do not have permission to modify linked registrations for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
 
 post:
   summary: Add relationships between a Node and linked Registrations
@@ -252,6 +254,8 @@ post:
       description: Forbidden. You do not have permission to modify linked registrations for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."
 
 delete:
   summary: Remove relationships between a Node and linked Registrations
@@ -317,3 +321,5 @@ delete:
       description: Forbidden. You do not have permission to modify linked registrations for this node.
     '404':
       description: Not Found. No node matches the given ID.
+    '405':
+      description: Returned if write access to this node has been restricted. The response will include the message "This action is no longer available. Contact support if you have any questions."