From dde42b789ca4399fadb96482143c1d6185224a9e Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Mon, 10 Mar 2025 14:48:54 -0400 Subject: [PATCH 01/21] add first draft of Notification Subscription section --- ...llection_provider_subscription_detail.yaml | 182 ++++++++++++++++ ...collection_provider_subscription_list.yaml | 50 +++++ .../collection_subscription_detail.yaml | 170 +++++++++++++++ swagger-spec/subscriptions/definition.yaml | 150 +++++++++++++ ...preprint_provider_subscription_detail.yaml | 167 +++++++++++++++ .../preprint_provider_subscription_list.yaml | 39 ++++ ...stration_provider_subscription_detail.yaml | 200 ++++++++++++++++++ ...gistration_provider_subscription_list.yaml | 33 +++ .../registration_subscription_detail.yaml | 118 +++++++++++ .../registration_subscription_list.yaml | 155 ++++++++++++++ .../subscriptions/subscription_detail.yaml | 160 ++++++++++++++ .../subscriptions/subscription_list.yaml | 133 ++++++++++++ swagger-spec/swagger.yaml | 115 +++++++++- 13 files changed, 1670 insertions(+), 2 deletions(-) create mode 100644 swagger-spec/subscriptions/collection_provider_subscription_detail.yaml create mode 100644 swagger-spec/subscriptions/collection_provider_subscription_list.yaml create mode 100644 swagger-spec/subscriptions/collection_subscription_detail.yaml create mode 100644 swagger-spec/subscriptions/definition.yaml create mode 100644 swagger-spec/subscriptions/preprint_provider_subscription_detail.yaml create mode 100644 swagger-spec/subscriptions/preprint_provider_subscription_list.yaml create mode 100644 swagger-spec/subscriptions/registration_provider_subscription_detail.yaml create mode 100644 swagger-spec/subscriptions/registration_provider_subscription_list.yaml create mode 100644 swagger-spec/subscriptions/registration_subscription_detail.yaml create mode 100644 swagger-spec/subscriptions/registration_subscription_list.yaml create mode 100644 swagger-spec/subscriptions/subscription_detail.yaml create mode 100644 swagger-spec/subscriptions/subscription_list.yaml diff --git a/swagger-spec/subscriptions/collection_provider_subscription_detail.yaml b/swagger-spec/subscriptions/collection_provider_subscription_detail.yaml new file mode 100644 index 0000000..ab9bd08 --- /dev/null +++ b/swagger-spec/subscriptions/collection_provider_subscription_detail.yaml @@ -0,0 +1,182 @@ +# /providers/collections/{provider_id}/subscriptions/{subscription_id}/ + +get: + summary: Retrieve a Collection Provider Notification Subscription + description: >- + Retrieve the details of a specific notification subscription associated with a collection provider. + + ## Permissions + - The authenticated user must be the owner of the subscription. + + ## Returns + - A JSON object with a `data` key containing the subscription details. + - Each subscription describes the event being subscribed to and the frequency at which notifications are sent. + + tags: + - Notification Subscriptions + + operationId: collection_provider_subscription_detail + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the collection provider. + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + responses: + '200': + description: Successful retrieval of the subscription. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "collection123_subscription456" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "instant" + relationships: + user: + data: + type: "users" + id: "user_id" + provider: + data: + type: "providers" + id: "collection123" + links: + self: "https://api.osf.io/v2/providers/collections/collection123/subscriptions/collection123_subscription456/" + meta: + version: "2.0" + '401': + description: Unauthorized. Authentication credentials are missing or invalid. + '403': + description: Forbidden. You do not have permission to access this subscription. + '404': + description: Not Found. No subscription matches the given ID or the collection provider does not exist. + +patch: + summary: Update a Collection Provider Notification Subscription + description: >- + Update the notification frequency for a specific subscription associated with a collection provider. + + #### Permissions + - The authenticated user must be the owner of the subscription. + + #### Request Body + Provide the `frequency` attribute within the `attributes` object to update the subscription. + + #### Available Frequency Values: + - `instant`: Immediate email notifications. + - `daily`: Daily summary emails. + - `none`: Disable email notifications. + + #### Returns + - A JSON object with the updated subscription details under the `data` key if the update is successful. + - If unsuccessful, returns an `errors` object detailing the validation issues. + + tags: + - Notification Subscriptions + + operationId: collection_provider_subscription_patch + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the collection provider. + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + - in: body + name: body + required: true + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + - attributes + properties: + type: + type: string + enum: + - subscription + description: Must be `subscription`. + id: + type: string + description: The unique identifier of the subscription. + attributes: + type: object + required: + - frequency + properties: + frequency: + type: string + enum: + - instant + - daily + - none + description: | + The notification frequency for this subscription. + - `instant`: Immediate email notifications. + - `daily`: Daily summary emails. + - `none`: No notifications. + + example: + data: + type: subscription + id: "collection123_subscription456" + attributes: + frequency: "daily" + + responses: + '200': + description: Subscription successfully updated. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "collection123_subscription456" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "daily" + relationships: + user: + data: + type: "users" + id: "user_id" + provider: + data: + type: "providers" + id: "collection123" + links: + self: "https://api.osf.io/v2/providers/collections/collection123/subscriptions/collection123_subscription456/" + meta: + version: "2.0" + '400': + description: Bad Request. Invalid input provided or missing required fields. + '401': + description: Unauthorized. Authentication credentials are missing or invalid. + '403': + description: Forbidden. You do not have permission to update this subscription. + '404': + description: Not Found. No subscription matches the given ID or the collection provider does not exist. diff --git a/swagger-spec/subscriptions/collection_provider_subscription_list.yaml b/swagger-spec/subscriptions/collection_provider_subscription_list.yaml new file mode 100644 index 0000000..51db32a --- /dev/null +++ b/swagger-spec/subscriptions/collection_provider_subscription_list.yaml @@ -0,0 +1,50 @@ +get: + summary: List Notification Subscriptions for a Collection Provider + description: >- + Retrieve a paginated list of notification subscriptions associated with a specific collection provider + for the authenticated user. + + Each subscription resource represents the user's notification preferences for specific events + (e.g., new pending submissions) within the specified collection provider. + + ## Permissions + - The user must be authenticated. + - The user must have existing subscriptions for the specified collection provider. + + ## Response Format + - Returns a JSON:API compliant response with a `data` array containing subscription resources. + - Each subscription includes: + - `event_name`: The event that triggers notifications (e.g., `new_pending_submissions`). + - `frequency`: How often notifications are sent (`instant`, `daily`, `none`). + - `provider`: Relationship object linking to the collection provider. + + ## Pagination + - Standard JSON:API pagination links (`first`, `last`, `prev`, `next`) and `meta` information + (e.g., `total`, `per_page`) are included in the response. + + + parameters: + - in: path + type: string + name: provider_id + required: true + description: 'The unique identifier of the collection provider.' + + tags: + - Notification Subscriptions + + operationId: collection_provider_subscription_list + + responses: + '200': + description: Successful response with a paginated list of subscriptions. + examples: + application/json: + schema: + $ref: 'definition.yaml' + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. The user does not have permission to access subscriptions for this provider. + '404': + description: Not Found. The specified collection provider does not exist or has no subscriptions for the user. diff --git a/swagger-spec/subscriptions/collection_subscription_detail.yaml b/swagger-spec/subscriptions/collection_subscription_detail.yaml new file mode 100644 index 0000000..8d698f3 --- /dev/null +++ b/swagger-spec/subscriptions/collection_subscription_detail.yaml @@ -0,0 +1,170 @@ +# /collection_subscriptions/{subscription_id}/ +get: + summary: Retrieve a Collection Subscription + description: >- + Retrieve the details of a specific notification subscription associated with a collection provider. + + ## Permissions + - The authenticated user **must** be the owner of the subscription. + - Access is restricted to subscriptions owned by the requesting user. + + ## Returns + - A JSON:API compliant representation of the subscription resource. + - Includes event name, frequency, user, provider, and related links. + + tags: + - Notification Subscriptions + + operationId: collection_subscription_detail + + parameters: + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + responses: + '200': + description: Subscription successfully retrieved. + schema: + $ref: 'definition.yaml' # Or use '#/components/schemas/Subscription' if OpenAPI 3 + examples: + application/json: + data: + id: "collection123_subscription456" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "instant" + relationships: + user: + data: + type: "users" + id: "user_id" + provider: + data: + type: "providers" + id: "collection123" + links: + self: "https://api.osf.io/v2/collection_subscriptions/collection123_subscription456/" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view this subscription. + '404': + description: Not Found. No subscription found matching the given ID. + +patch: + summary: Update a Collection Subscription + description: >- + Update the notification frequency for a specific collection provider subscription. + + ## Permissions + - The authenticated user **must** be the owner of the subscription. + - Only the `frequency` attribute can be modified. + + ## Request Body + Provide the `frequency` inside the `attributes` object. Valid values include: + - `instant`: Immediate email notifications. + - `daily`: Daily digest emails. + - `none`: Disable notifications for this event. + + ## Returns + - A JSON:API compliant representation of the updated subscription resource. + + tags: + - Notification Subscriptions + + operationId: collection_subscription_update + + parameters: + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + - in: body + name: body + required: true + description: JSON:API-compliant payload specifying the updated subscription attributes. + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + - attributes + properties: + type: + type: string + enum: + - subscription + description: Must be `subscription`. + id: + type: string + description: The unique identifier of the subscription. + attributes: + type: object + required: + - frequency + properties: + frequency: + type: string + enum: + - instant + - daily + - none + description: | + The notification frequency for this subscription. + - `instant`: Immediate email notifications. + - `daily`: Daily digest emails. + - `none`: No notifications. + + example: + data: + type: subscription + id: "collection123_subscription456" + attributes: + frequency: "daily" + + consumes: + - application/json + + responses: + '200': + description: Subscription successfully updated. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "collection123_subscription456" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "daily" + relationships: + user: + data: + type: "users" + id: "user_id" + provider: + data: + type: "providers" + id: "collection123" + links: + self: "https://api.osf.io/v2/collection_subscriptions/collection123_subscription456/" + '400': + description: Bad Request. Invalid input provided. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to update this subscription. + '404': + description: Not Found. No subscription matches the given ID. diff --git a/swagger-spec/subscriptions/definition.yaml b/swagger-spec/subscriptions/definition.yaml new file mode 100644 index 0000000..1a2a454 --- /dev/null +++ b/swagger-spec/subscriptions/definition.yaml @@ -0,0 +1,150 @@ +type: object +title: Subscription +description: | + A Subscription resource represents a user's notification preferences for specific events + occurring on the OSF. Subscriptions can be global or tied to specific providers such as + collections, preprints, or registrations. + +properties: + id: + type: string + readOnly: true + description: | + The unique identifier of the Subscription. + This corresponds to the `_id` field on the NotificationSubscription model. + + type: + type: string + readOnly: true + enum: + - subscription + description: | + The type identifier of this resource. Always `subscription`. + + attributes: + type: object + title: Attributes + description: | + Attributes describing the subscription event and notification frequency. + properties: + event_name: + type: string + readOnly: true + description: | + The name of the event that triggers this subscription. + Possible values include: + - `global_comments` + - `global_mentions` + - `global_reviews` + - `global_comment_replies` + - `comments` + - `file_updated` + - `new_pending_submissions` + frequency: + type: string + description: | + The notification frequency for the subscribed event. + Accepted values: + - `instant`: Receive email notifications immediately when the event occurs. + - `daily`: Receive a daily summary email. + - `none`: Do not receive notifications for this subscription. + enum: + - instant + - daily + - none + + relationships: + type: object + title: Relationships + description: | + Links to related resources: the user and (optionally) a provider. + properties: + user: + type: object + description: | + The user associated with this subscription. + properties: + links: + type: object + properties: + related: + type: string + format: uri + description: | + A link to the user resource. + data: + type: object + properties: + type: + type: string + enum: + - users + description: | + The resource type (`users`). + id: + type: string + description: | + The unique identifier of the user. + + provider: + type: object + description: | + The provider associated with this subscription. + This can be a Collection Provider, Preprint Provider, or Registration Provider. + properties: + links: + type: object + properties: + related: + type: string + format: uri + description: | + A link to the provider resource. + data: + type: object + properties: + type: + type: string + enum: + - providers + description: | + The resource type (`providers`). + id: + type: string + description: | + The unique identifier of the provider. + + links: + type: object + title: Links + description: | + Links to alternative representations or actions for the Subscription resource. + properties: + self: + type: string + format: uri + description: | + A link to the detail page for this subscription. + +example: + data: + id: "abcd1234" + type: subscription + attributes: + event_name: "new_pending_submissions" + frequency: "instant" + relationships: + user: + data: + type: users + id: user_id + links: + related: "https://api.osf.io/v2/users/user_id/" + provider: + data: + type: providers + id: provider_id + links: + related: "https://api.osf.io/v2/providers/collections/provider_id/" + links: + self: "https://api.osf.io/v2/subscriptions/abcd1234/" diff --git a/swagger-spec/subscriptions/preprint_provider_subscription_detail.yaml b/swagger-spec/subscriptions/preprint_provider_subscription_detail.yaml new file mode 100644 index 0000000..6223a4a --- /dev/null +++ b/swagger-spec/subscriptions/preprint_provider_subscription_detail.yaml @@ -0,0 +1,167 @@ +get: + summary: Retrieve a Preprint Provider Subscription + description: >- + Retrieve details of an individual notification subscription associated with a preprint provider. + + ## Permissions + + User must be authenticated and subscribed to the specified preprint provider notification. + + ## Returns + + A JSON object containing details about the requested subscription, including frequency, event type, and provider information. + + parameters: + - in: path + type: string + name: provider_id + required: true + description: The unique identifier of the preprint provider. + - in: path + type: string + name: subscription_id + required: true + description: The unique identifier of the subscription. + + tags: + - Notification Subscriptions + operationId: preprint_provider_subscription_detail + responses: + '200': + description: OK + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "provider123_subscription456" + type: + type: string + example: "notification_subscriptions" + attributes: + type: object + properties: + frequency: + type: string + enum: + - none + - email_digest + - email_transactional + event_name: + type: string + example: "preprint_added" + provider_name: + type: string + example: "TestArXiv" + provider_id: + type: string + example: "testarxiv" + links: + type: object + properties: + self: + type: string + format: uri + example: "https://api.osf.io/v2/providers/preprints/testarxiv/subscriptions/provider123_subscription456/" + '401': + description: Unauthorized + '403': + description: Forbidden + '404': + description: Not Found + +patch: + summary: Update a Preprint Provider Subscription + description: >- + Updates a preprint provider subscription by setting the values specified in the request body. + Unspecified attributes remain unchanged. + + The subscription can be updated using a **PATCH** request. The only editable attribute is `frequency`. + + ## Permissions + + User must be authenticated and the owner of the subscription. + + ## Returns + + A JSON object containing the updated subscription details. + + parameters: + - in: path + type: string + name: provider_id + required: true + description: The unique identifier of the preprint provider. + - in: path + type: string + name: subscription_id + required: true + description: The unique identifier of the subscription. + - in: body + name: body + required: true + schema: + type: object + example: + data: + type: notification_subscriptions + id: "provider123_subscription456" + attributes: + frequency: "email_digest" + + tags: + - Notification Subscriptions + operationId: preprint_provider_subscription_update + consumes: + - application/json + responses: + '200': + description: OK + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "provider123_subscription456" + type: + type: string + example: "notification_subscriptions" + attributes: + type: object + properties: + frequency: + type: string + enum: + - none + - email_digest + - email_transactional + event_name: + type: string + example: "preprint_added" + provider_name: + type: string + example: "TestArXiv" + provider_id: + type: string + example: "testarxiv" + links: + type: object + properties: + self: + type: string + format: uri + example: "https://api.osf.io/v2/providers/preprints/testarxiv/subscriptions/provider123_subscription456/" + '400': + description: Bad Request + '401': + description: Unauthorized + '403': + description: Forbidden + '404': + description: Not Found diff --git a/swagger-spec/subscriptions/preprint_provider_subscription_list.yaml b/swagger-spec/subscriptions/preprint_provider_subscription_list.yaml new file mode 100644 index 0000000..51aa189 --- /dev/null +++ b/swagger-spec/subscriptions/preprint_provider_subscription_list.yaml @@ -0,0 +1,39 @@ +get: + summary: List Preprint Provider Subscriptions + description: >- + Retrieve a paginated list of notification subscriptions for a specific preprint provider associated with the authenticated user. + + ## Permissions + + User must be authenticated and must have subscriptions for the specified preprint provider. + + ## Returns + + A JSON object with a paginated list of notification subscriptions, including subscription frequency, event type, and provider details. + + parameters: + - in: path + type: string + name: provider_id + required: true + description: The unique identifier of the preprint provider. + - in: query + type: integer + name: page + required: false + description: The page number of results to retrieve. + + tags: + - Notification Subscriptions + operationId: preprint_provider_subscription_list + responses: + '200': + description: OK + schema: + $ref: 'definition.yaml' + '401': + description: Unauthorized + '403': + description: Forbidden + '404': + description: Not Found diff --git a/swagger-spec/subscriptions/registration_provider_subscription_detail.yaml b/swagger-spec/subscriptions/registration_provider_subscription_detail.yaml new file mode 100644 index 0000000..e70aacc --- /dev/null +++ b/swagger-spec/subscriptions/registration_provider_subscription_detail.yaml @@ -0,0 +1,200 @@ +# /providers/registrations/{provider_id}/subscriptions/{subscription_id}/ + +get: + summary: Retrieve a Registration Provider Notification Subscription + description: >- + Retrieve the details of a specific notification subscription associated with a registration provider. + + This endpoint allows an authenticated user to view their current subscription preferences for events related to a specific registration provider. + + ## Permissions + - The requesting user **must be authenticated**. + - The requesting user **must be the owner** of the subscription. + + Unauthorized or forbidden access attempts will result in `401 Unauthorized` or `403 Forbidden` errors. + + ## Returns + A JSON object representing the notification subscription, including: + + - `id`: Unique identifier of the subscription. + - `type`: Resource type (always `subscription`). + - `attributes`: Event type and notification frequency. + - `relationships`: Links to the associated user and provider resources. + - `links`: A `self` link to this subscription resource. + + tags: + - Notification Subscriptions + + operationId: registration_provider_subscription_detail + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration provider associated with this subscription. + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + responses: + '200': + description: Subscription successfully retrieved. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "reg123_subscription456" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "instant" + relationships: + user: + data: + type: "users" + id: "user_id" + provider: + data: + type: "providers" + id: "reg123" + links: + self: "https://api.osf.io/v2/providers/registrations/reg123/subscriptions/reg123_subscription456/" + meta: + version: "2.0" + '401': + description: Unauthorized. Authentication credentials are missing or invalid. + '403': + description: Forbidden. You do not have permission to access this subscription. + '404': + description: Not Found. The subscription or provider does not exist. + +patch: + summary: Update a Registration Provider Notification Subscription + description: >- + Update a specific notification subscription associated with a registration provider. + + Typically, this endpoint is used to change the notification `frequency` for the subscription. + + ## Permissions + - The requesting user **must be authenticated**. + - The requesting user **must be the owner** of the subscription. + + Unauthorized or forbidden access attempts will result in `401 Unauthorized` or `403 Forbidden` errors. + + ## Request Body + Provide the subscription ID and the updated `frequency` attribute. + + ## Available Frequency Values + - `instant`: Immediate email notifications. + - `daily`: Daily summary emails. + - `none`: No notifications. + + ## Returns + A JSON object representing the updated subscription. + + tags: + - Notification Subscriptions + + operationId: registration_provider_subscription_patch + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration provider associated with this subscription. + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + - in: body + name: body + required: true + description: JSON API-formatted payload specifying the updated subscription attributes. + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + - attributes + properties: + type: + type: string + enum: + - subscription + description: The resource type. Must be `subscription`. + id: + type: string + description: The unique identifier of the subscription. + attributes: + type: object + required: + - frequency + properties: + frequency: + type: string + enum: + - instant + - daily + - none + description: | + Determines how frequently the user receives notifications. + - `instant`: Immediate email notifications. + - `daily`: Daily summary emails. + - `none`: No notifications. + + example: + data: + type: subscription + id: "reg123_subscription456" + attributes: + frequency: "daily" + + consumes: + - application/json + + responses: + '200': + description: Subscription successfully updated. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "reg123_subscription456" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "daily" + relationships: + user: + data: + type: "users" + id: "user_id" + provider: + data: + type: "providers" + id: "reg123" + links: + self: "https://api.osf.io/v2/providers/registrations/reg123/subscriptions/reg123_subscription456/" + meta: + version: "2.0" + '400': + description: Bad Request. The request body is malformed or missing required fields. + '401': + description: Unauthorized. Authentication credentials are missing or invalid. + '403': + description: Forbidden. You do not have permission to modify this subscription. + '404': + description: Not Found. The subscription or provider does not exist. diff --git a/swagger-spec/subscriptions/registration_provider_subscription_list.yaml b/swagger-spec/subscriptions/registration_provider_subscription_list.yaml new file mode 100644 index 0000000..4f6deff --- /dev/null +++ b/swagger-spec/subscriptions/registration_provider_subscription_list.yaml @@ -0,0 +1,33 @@ +get: + summary: List Registration Provider Subscriptions + description: >- + Retrieve a list of notification subscriptions for a specific registration provider associated with the authenticated user. + + ## Permissions + + User must be authenticated to access their registration provider subscriptions. + + ## Returns + + A paginated JSON object containing notification subscriptions for the registration provider. + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration provider. + - in: query + name: page + type: integer + required: false + description: Page number of the results to retrieve. + + tags: + - Notification Subscriptions + operationId: registration_subscription_list + responses: + '200': + description: OK + schema: + $ref: 'definition.yaml' \ No newline at end of file diff --git a/swagger-spec/subscriptions/registration_subscription_detail.yaml b/swagger-spec/subscriptions/registration_subscription_detail.yaml new file mode 100644 index 0000000..4df8946 --- /dev/null +++ b/swagger-spec/subscriptions/registration_subscription_detail.yaml @@ -0,0 +1,118 @@ +get: + summary: Retrieve a Registration Provider Subscription + description: >- + Retrieve details of a specific notification subscription for a registration provider. + + ## Permissions + + The user must be authenticated and have permission to access the specified registration provider subscription. + + ## Returns + + A JSON object containing details of the notification subscription for the registration provider. + + parameters: + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + tags: + - Notification Subscriptions + operationId: registration_subscription_detail + responses: + '200': + description: OK + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "reg123_subscription456" + type: + type: string + example: "notification_subscriptions" + attributes: + type: object + properties: + frequency: + type: string + enum: + - none + - email_digest + - email_transactional + example: "email_transactional" + event_name: + type: string + example: "new_pending_registration" + provider_name: + type: string + example: "TestRegistrationProvider" + provider_id: + type: string + example: "reg123" + links: + type: object + properties: + self: + type: string + format: uri + example: "https://api.osf.io/v2/providers/registrations/reg123/subscriptions/reg123_subscription456/" + '401': + description: Unauthorized + '403': + description: Forbidden + '404': + description: Not Found + +patch: + summary: Update a Registration Provider Subscription + description: >- + Update the frequency of a specific notification subscription for a registration provider. + + ## Permissions + + User must be authenticated and be the owner of the subscription to modify it. + + ## Returns + + A JSON object containing the updated details of the notification subscription. + + parameters: + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + - in: body + name: body + required: true + schema: + type: object + example: + data: + type: notification_subscriptions + id: "reg123_subscription456" + attributes: + frequency: "none" + + tags: + - Notification Subscriptions + operationId: registration_subscription_update + consumes: + - application/json + responses: + '200': + description: OK + '400': + description: Bad Request + '401': + description: Unauthorized + '403': + description: Forbidden + '404': + description: Not Found diff --git a/swagger-spec/subscriptions/registration_subscription_list.yaml b/swagger-spec/subscriptions/registration_subscription_list.yaml new file mode 100644 index 0000000..04a11a1 --- /dev/null +++ b/swagger-spec/subscriptions/registration_subscription_list.yaml @@ -0,0 +1,155 @@ +get: + summary: Retrieve Registration Provider Notification Subscriptions + description: >- + Retrieve a paginated list of notification subscriptions associated with a specific registration provider. + Each subscription resource details a user's preferences for receiving notifications on specific events, + such as new pending registrations. + + ## Permissions + + - The user **must be authenticated**. + - The user must have existing subscriptions associated with the specified registration provider. + + ## Returns + + Returns a JSON:API-compliant paginated list of subscription resources. + + Each subscription includes: + - `event_name`: The event that triggers notifications (e.g., `new_pending_submissions`). + - `frequency`: The notification frequency (e.g., `instant`, `daily`, `none`). + - `relationships`: Links to the provider and user entities. + - `links`: A `self` link to the subscription resource. + + tags: + - Notification Subscriptions + + operationId: registration_provider_subscription_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration provider. + + - in: query + name: page + type: integer + required: false + description: The page number of the results to retrieve. + + responses: + '200': + description: Successful retrieval of a paginated list of notification subscriptions for the registration provider. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "reg123_subscription456" + type: + type: string + example: "subscription" + attributes: + type: object + properties: + event_name: + type: string + example: "new_pending_submissions" + frequency: + type: string + enum: + - instant + - daily + - none + example: "instant" + relationships: + type: object + properties: + user: + type: object + properties: + data: + type: object + properties: + type: + type: string + example: "users" + id: + type: string + example: "user123" + links: + type: object + properties: + related: + type: string + format: uri + example: "https://api.osf.io/v2/users/user123/" + provider: + type: object + properties: + data: + type: object + properties: + type: + type: string + example: "providers" + id: + type: string + example: "reg123" + links: + type: object + properties: + related: + type: string + format: uri + example: "https://api.osf.io/v2/providers/registrations/reg123/" + links: + type: object + properties: + self: + type: string + format: uri + example: "https://api.osf.io/v2/providers/registrations/reg123/subscriptions/reg123_subscription456/" + + links: + type: object + properties: + first: + type: string + format: uri + example: "https://api.osf.io/v2/providers/registrations/reg123/subscriptions/?page=1" + last: + type: string + format: uri + example: "https://api.osf.io/v2/providers/registrations/reg123/subscriptions/?page=4" + prev: + type: string + format: uri + example: null + next: + type: string + format: uri + example: "https://api.osf.io/v2/providers/registrations/reg123/subscriptions/?page=2" + + meta: + type: object + properties: + total: + type: integer + example: 33 + per_page: + type: integer + example: 10 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. The user does not have permission to access subscriptions for this provider. + '404': + description: Not Found. The specified registration provider does not exist or has no subscriptions for the user. diff --git a/swagger-spec/subscriptions/subscription_detail.yaml b/swagger-spec/subscriptions/subscription_detail.yaml new file mode 100644 index 0000000..b0e9e0b --- /dev/null +++ b/swagger-spec/subscriptions/subscription_detail.yaml @@ -0,0 +1,160 @@ +# /subscriptions/{subscription_id}/ +get: + summary: Retrieve a Notification Subscription + description: >- + Retrieve the details of a specific notification subscription, including its event name and notification frequency. + + #### Permissions + - The authenticated user must be the owner of the subscription. + + #### Returns + - A JSON object with a `data` key containing the subscription details. + - Each subscription describes the event being subscribed to and the frequency at which notifications are sent. + + tags: + - Notification Subscriptions + + operationId: subscription_detail + + parameters: + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + responses: + '200': + description: Successful retrieval of the subscription. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "{subscription_id}" + type: "subscription" + attributes: + event_name: "global_mentions" + frequency: "instant" + relationships: + user: + data: + type: "users" + id: "user_id" + provider: + data: + type: "providers" + id: "provider_id" + links: + self: "https://api.test.osf.io/v2/subscriptions/{subscription_id}/" + meta: + version: "2.0" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access this subscription. + '404': + description: Not Found. No subscription matches the given ID. + +patch: + summary: Update a Notification Subscription + description: >- + Update the notification frequency for a specific subscription. Only the frequency attribute can be modified. + + ## Permissions + + - The authenticated user must be the owner of the subscription. + + ## Request Body + + Provide the `frequency` attribute within the `attributes` object to update the subscription. + Available values for `frequency` are: + - `instant`: Receive immediate email notifications. + - `daily`: Receive a daily summary email. + - `none`: Disable email notifications for this subscription. + + ## Returns + + - A JSON object with the updated subscription details under the `data` key if the update is successful. + - If unsuccessful, returns an `errors` object detailing the validation issues. + + tags: + - Notification Subscriptions + + operationId: subscription_update + + parameters: + - in: path + name: subscription_id + type: string + required: true + description: The unique identifier of the notification subscription. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: object + required: + - type + - id + - attributes + properties: + type: + type: string + enum: + - subscription + description: Must be `subscription`. + id: + type: string + description: The unique identifier of the subscription. + attributes: + type: object + required: + - frequency + properties: + frequency: + type: string + enum: + - instant + - daily + - none + description: | + The notification frequency for this subscription. + - `instant`: Immediate email notifications. + - `daily`: Daily summary emails. + - `none`: No notifications. + + example: + data: + type: subscription + id: "{subscription_id}" + attributes: + frequency: "daily" + + responses: + '200': + description: Subscription successfully updated. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "{subscription_id}" + type: "subscription" + attributes: + event_name: "global_mentions" + frequency: "daily" + links: + self: "https://api.test.osf.io/v2/subscriptions/{subscription_id}/" + '400': + description: Bad Request. Invalid input provided. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify this subscription. + '404': + description: Not Found. No subscription matches the given ID. diff --git a/swagger-spec/subscriptions/subscription_list.yaml b/swagger-spec/subscriptions/subscription_list.yaml new file mode 100644 index 0000000..da25925 --- /dev/null +++ b/swagger-spec/subscriptions/subscription_list.yaml @@ -0,0 +1,133 @@ +# /subscriptions/ +get: + summary: Retrieve a List of Notification Subscriptions + description: >- + Retrieve a paginated list of the authenticated user's notification subscriptions. + + Each subscription describes the user's preferences for receiving notifications about specific events + on OSF resources such as projects, preprints, registrations, or collections. + + ## Permissions + + - The authenticated user can only retrieve their own subscriptions. + - Authentication is required. + + ## Returns + + - A JSON object containing a `data` array of subscription resources, each representing a single subscription. + - Each subscription includes details such as the `event_name`, `frequency`, and links to related resources. + - The response also includes `links` and `meta` keys for pagination support. + + tags: + - Notification Subscriptions + + operationId: subscriptions_list + + parameters: + - in: query + name: page + type: integer + required: false + description: The page number of the paginated result set. + + - in: query + name: filter[event_name] + type: string + required: false + description: Filter subscriptions by `event_name`. + + responses: + '200': + description: Successful retrieval of the user's notification subscriptions. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + - id: "mindrxiv_new_pending_submissions" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "instant" + links: + self: "https://api.test.osf.io/v2/subscriptions/mindrxiv_new_pending_submissions/" + - id: "eartharxiv_new_pending_submissions" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "instant" + links: + self: "https://api.test.osf.io/v2/subscriptions/eartharxiv_new_pending_submissions/" + - id: "osf.io/preprints/africar_new_pending_submissions" + type: "subscription" + attributes: + event_name: "new_pending_submissions" + frequency: "instant" + links: + self: "https://api.test.osf.io/v2/subscriptions/osf.io/preprints/africar_new_pending_submissions/" + - id: "ydhnf_global_comment_replies" + type: "subscription" + attributes: + event_name: "global_comment_replies" + frequency: "none" + links: + self: "https://api.test.osf.io/v2/subscriptions/ydhnf_global_comment_replies/" + - id: "ydhnf_global_comments" + type: "subscription" + attributes: + event_name: "global_comments" + frequency: "daily" + links: + self: "https://api.test.osf.io/v2/subscriptions/ydhnf_global_comments/" + - id: "ydhnf_global_file_updated" + type: "subscription" + attributes: + event_name: "global_file_updated" + frequency: "daily" + links: + self: "https://api.test.osf.io/v2/subscriptions/ydhnf_global_file_updated/" + - id: "ydhnf_global_mentions" + type: "subscription" + attributes: + event_name: "global_mentions" + frequency: "instant" + links: + self: "https://api.test.osf.io/v2/subscriptions/ydhnf_global_mentions/" + - id: "ydhnf_global_reviews" + type: "subscription" + attributes: + event_name: "global_reviews" + frequency: "daily" + links: + self: "https://api.test.osf.io/v2/subscriptions/ydhnf_global_reviews/" + - id: "vbks5_file_updated" + type: "subscription" + attributes: + event_name: "file_updated" + frequency: "instant" + links: + self: "https://api.test.osf.io/v2/subscriptions/vbks5_file_updated/" + - id: "vbks5_comments" + type: "subscription" + attributes: + event_name: "comments" + frequency: "instant" + links: + self: "https://api.test.osf.io/v2/subscriptions/vbks5_comments/" + links: + self: "https://api.test.osf.io/v2/subscriptions/?page=1" + first: "https://api.test.osf.io/v2/subscriptions/?page=1" + prev: null + next: "https://api.test.osf.io/v2/subscriptions/?page=2" + last: "https://api.test.osf.io/v2/subscriptions/?page=4" + meta: + total: 33 + per_page: 10 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access these subscriptions. + '404': + description: Not Found. No subscriptions found for the user. diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index e05951d..1f5cf82 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -50,6 +50,7 @@ x-tagGroups: - Schema Responses - Schema Response Actions - Nodes + - Notification Subscriptions - Preprints - Preprint Providers - Draft Registrations @@ -854,8 +855,84 @@ tags: adheres to the standards set for collection submissions. It aids in providing transparency and order to the process of managing collections and ensures that moderators and admins have the tools and information they need to effectively manage collection submissions. - - + - name: Notification Subscriptions + description: >- + **Notification Subscriptions** allow users to manage how they receive alerts about activities and events + related to OSF resources, such as projects, preprints, registrations, and collections. Subscriptions control + **when** notifications are sent and **which events** trigger them. + + These subscriptions are **private** and are only visible to the authenticated user who owns them. + + ### Subscription Scope and Types + + Subscriptions can be configured at different scopes depending on the resource type: + + - **Global Subscriptions** + Apply OSF-wide, affecting events like comment replies, mentions, and review updates across all resources. + + - **Node Subscriptions** + Apply to individual projects or components (nodes), tracking events such as new comments or file updates. + + - **Provider Subscriptions** + Apply to resources within a specific provider (collection, preprint, or registration providers). These subscriptions + typically track events relevant to moderation workflows, such as new pending submissions. + + ### Attributes + + - `event_name` + The specific event that triggers this subscription. + Available event names depend on the scope of the subscription. Examples include: + - `comments` + - `file_updated` + - `global_mentions` + - `new_pending_submissions` + + - `frequency` + Determines how often the user receives notifications for the event: + - `instant`: Sends an email notification immediately after the event occurs. + - `daily`: Groups event notifications into a daily summary email. + - `none`: Disables notifications for the event. + + Users can update their notification frequency for each subscription. + + ### Relationships + + - `user` + The user who owns the subscription. Each subscription is tied to a single user. + - `provider` + The provider associated with the subscription, if applicable. This may be a Collection Provider, Preprint Provider, + or Registration Provider. Global subscriptions do not have a provider relationship. + + ### Available Event Names by Subscription Scope + + #### Node-Level Subscriptions + Subscriptions specific to individual projects or components: + - `comments`: Notify when comments are added. + - `file_updated`: Notify when files are updated. + + #### Global Subscriptions + Default notification preferences applied OSF-wide: + - `global_comment_replies`: Notify when someone replies to your comments. + - `global_comments`: Notify when comments are added to your projects. + - `global_file_updated`: Notify when files are updated in your projects. + - `global_mentions`: Notify when you are mentioned. + - `global_reviews`: Notify when your preprint submissions are updated. + + #### Provider-Level Subscriptions + Notifications related to moderation workflows or submissions within a specific provider: + - `new_pending_submissions`: Notify when new preprint submissions are awaiting moderation. + + ### Notification Channels + + Notifications are delivered via **email**, according to the selected `frequency`: + - `instant`: Immediate email notifications per event. + - `daily`: Batched email summary delivered daily. + - `none`: No email notifications are sent. + + ### Permissions and Access + + - Only the authenticated user who owns a subscription can view or update it. + - Subscriptions are managed via the OSF API and reflect the user's current notification preferences for supported events. paths: @@ -1379,3 +1456,37 @@ paths: /provider/collections/{collection_id}/moderators/{moderator_id}/: $ref: 'collection_provider/moderators_detail.yaml' + + ################################ + # NOTIFICATION SUBSCRIPTIONS # + ################################ + + /subscriptions/: + $ref: 'subscriptions/subscription_list.yaml' + + /subscriptions/{subscription_id}/: + $ref: 'subscriptions/subscription_detail.yaml' + + /providers/collections/{provider_id}/subscriptions/: + $ref: 'subscriptions/collection_provider_subscription_list.yaml' + + /providers/collections/{provider_id}/subscriptions/{subscription_id}/: + $ref: 'subscriptions/collection_provider_subscription_detail.yaml' + + /providers/preprints/{provider_id}/subscriptions/: + $ref: 'subscriptions/preprint_provider_subscription_list.yaml' + + /providers/preprints/{provider_id}/subscriptions/{subscription_id}/: + $ref: 'subscriptions/preprint_provider_subscription_detail.yaml' + + /providers/registrations/{provider_id}/subscriptions/: + $ref: 'subscriptions/registration_provider_subscription_list.yaml' + + /providers/registrations/{provider_id}/subscriptions/{subscription_id}/: + $ref: 'subscriptions/registration_provider_subscription_detail.yaml' + + /registration_subscriptions/{subscription_id}/: + $ref: 'subscriptions/registration_subscription_detail.yaml' + + /oollection_subscriptions/{subscription_id}/: + $ref: 'subscriptions/collection_subscription_detail.yaml' From 266225aa114733e92fbc015f3a5497a4df169fac Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Thu, 13 Mar 2025 11:13:52 -0400 Subject: [PATCH 02/21] Add actions and user settings --- swagger-spec/actions/action_detail.yaml | 98 ++++++++ swagger-spec/actions/definition.yaml | 187 ++++++++++++++++ .../actions/node_request_action_list.yaml | 176 +++++++++++++++ .../actions/preprint_request_action_list.yaml | 211 ++++++++++++++++++ swagger-spec/actions/review_action_list.yaml | 167 ++++++++++++++ swagger-spec/swagger.yaml | 88 +++++++- swagger-spec/users/user_claim.yaml | 101 +++++++++ .../users/user_draft_preprints_list.yaml | 99 ++++++++ .../users/user_draft_registrations_list.yaml | 99 ++++++++ swagger-spec/users/user_password.yaml | 97 ++++++++ .../user_relationships_institutions.yaml | 143 ++++++++++++ swagger-spec/users/user_settings.yaml | 156 +++++++++++++ .../users/user_settings_definition.yaml | 38 ++++ .../users/user_settings_email_detail.yaml | 200 +++++++++++++++++ .../users/user_settings_emails_list.yaml | 165 ++++++++++++++ swagger-spec/users/user_settings_export.yaml | 78 +++++++ .../user_settings_identities_detail.yaml | 118 ++++++++++ .../users/user_settings_identities_list.yaml | 63 ++++++ 18 files changed, 2282 insertions(+), 2 deletions(-) create mode 100644 swagger-spec/actions/action_detail.yaml create mode 100644 swagger-spec/actions/definition.yaml create mode 100644 swagger-spec/actions/node_request_action_list.yaml create mode 100644 swagger-spec/actions/preprint_request_action_list.yaml create mode 100644 swagger-spec/actions/review_action_list.yaml create mode 100644 swagger-spec/users/user_claim.yaml create mode 100644 swagger-spec/users/user_draft_preprints_list.yaml create mode 100644 swagger-spec/users/user_draft_registrations_list.yaml create mode 100644 swagger-spec/users/user_password.yaml create mode 100644 swagger-spec/users/user_relationships_institutions.yaml create mode 100644 swagger-spec/users/user_settings.yaml create mode 100644 swagger-spec/users/user_settings_definition.yaml create mode 100644 swagger-spec/users/user_settings_email_detail.yaml create mode 100644 swagger-spec/users/user_settings_emails_list.yaml create mode 100644 swagger-spec/users/user_settings_export.yaml create mode 100644 swagger-spec/users/user_settings_identities_detail.yaml create mode 100644 swagger-spec/users/user_settings_identities_list.yaml diff --git a/swagger-spec/actions/action_detail.yaml b/swagger-spec/actions/action_detail.yaml new file mode 100644 index 0000000..de74eab --- /dev/null +++ b/swagger-spec/actions/action_detail.yaml @@ -0,0 +1,98 @@ +# /actions/{action_id}/: + +get: + summary: Retrieve an Action by ID + description: >- + Retrieve the details of a specific Action by its unique identifier. + + Actions represent state transitions and comments on reviewable resources + such as preprints, registrations, node requests, schema responses, and + collection submissions. + + An Action includes information about who performed the action (creator), + the state change it caused (from_state to to_state), the trigger used to initiate + the action, and any optional comment. The action may also include links to + related resources, such as the target and the provider. + + #### Returns + + A JSON object with a `data` key containing the full representation of the action. + + #### Permissions + + - You must have at least read permissions on the resource the action applies to. + - Only authorized users can view non-public actions (`visible: false`). + + #### Errors + + If the request is unsuccessful, an `errors` key will be returned. Refer to the + [Errors and Error Codes documentation](#tag/Errors-and-Error-Codes) for more information. + + tags: + - Actions + operationId: action_detail_read + parameters: + - in: path + name: action_id + type: string + required: true + description: >- + The unique identifier of the action to retrieve. + + Example: `abc123` + responses: + '200': + description: Action retrieved successfully. + examples: + application/json: + data: + id: abc123 + type: review-actions + attributes: + trigger: accept + comment: "The submission was approved by the moderator." + from_state: pending + to_state: accepted + date_created: '2024-01-01T00:00:00Z' + date_modified: '2024-01-01T01:00:00Z' + auto: false + visible: true + relationships: + creator: + links: + related: + href: 'https://api.osf.io/v2/users/user456/' + meta: {} + data: + id: user456 + type: users + target: + links: + related: + href: 'https://api.osf.io/v2/preprints/preprint789/' + meta: {} + data: + id: preprint789 + type: preprints + provider: + links: + related: + href: 'https://api.osf.io/v2/providers/osf/' + meta: {} + data: + id: osf + type: providers + links: + self: 'https://api.osf.io/v2/actions/abc123/' + '403': + description: >- + Permission denied. + + You do not have permission to view this action. Only users with the + appropriate permissions on the resource or provider can view actions. + '404': + description: >- + Action not found. + + The specified action ID does not exist or is not accessible. Ensure you + have the correct ID and necessary permissions. diff --git a/swagger-spec/actions/definition.yaml b/swagger-spec/actions/definition.yaml new file mode 100644 index 0000000..e661656 --- /dev/null +++ b/swagger-spec/actions/definition.yaml @@ -0,0 +1,187 @@ +description: >- + An Action represents a state transition, accompanied by an optional comment, on a reviewable object. + Actions are used to track moderation and request decisions on resources like Preprints, Registrations, + Node Requests, Schema Responses, and Collection Submissions. + + Each Action records who performed the action (the creator), the state change (`from_state` → `to_state`), + and the `trigger` event that initiated the change. Optional comments may provide additional context. + + Actions are typically created when moderators or administrators perform moderation or review workflows. + Some actions can be triggered automatically (`auto: true`), such as system transitions. + +type: object +required: + - id + - type + - attributes + - relationships +properties: + id: + type: string + description: The unique identifier of the action. + example: abc123 + + type: + type: string + enum: [review-actions, node-request-actions, preprint-request-actions, registration-actions, schema-response-actions, collection-submission-actions] + description: The type of action resource. + example: review-actions + + attributes: + type: object + required: + - trigger + - from_state + - to_state + - date_created + - date_modified + properties: + trigger: + type: string + description: >- + The trigger that initiated the action. + Triggers correspond to state changes in the workflow and may include submit, accept, reject, withdraw, etc. + example: accept + + comment: + type: string + description: >- + Optional comment explaining the rationale for the action or providing additional details. + example: "This submission looks good to me." + + from_state: + type: string + description: >- + The state of the resource before the action was performed. + This reflects the resource's state prior to the trigger being executed. + example: pending + + to_state: + type: string + description: >- + The state of the resource after the action was performed. + This reflects the resource's updated state as a result of the trigger. + example: accepted + + date_created: + type: string + format: date-time + description: The date and time when the action was created. + example: '2024-01-01T00:00:00Z' + + date_modified: + type: string + format: date-time + description: The date and time when the action was last modified. + example: '2024-01-01T01:00:00Z' + + auto: + type: boolean + description: >- + Indicates whether the action was automatically generated by the system (true), + or manually triggered by a user (false). + example: false + + visible: + type: boolean + description: >- + Indicates whether the action is visible to non-admin users (true) or only visible to admins and moderators (false). + Visibility typically depends on the provider's review workflow and moderation settings. + example: true + + relationships: + type: object + required: + - creator + - target + properties: + creator: + description: The user who performed the action. + type: object + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: 'https://api.osf.io/v2/users/user456/' + meta: + type: object + example: {} + data: + type: object + properties: + id: + type: string + example: user456 + type: + type: string + example: users + + target: + description: The resource (preprint, registration, node request, etc.) on which the action was performed. + type: object + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: 'https://api.osf.io/v2/preprints/preprint789/' + meta: + type: object + example: {} + data: + type: object + properties: + id: + type: string + example: preprint789 + type: + type: string + example: preprints + + provider: + description: >- + The provider responsible for managing the review or moderation workflow for the target resource. + type: object + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: 'https://api.osf.io/v2/providers/osf/' + meta: + type: object + example: {} + data: + type: object + properties: + id: + type: string + example: osf + type: + type: string + example: providers + + links: + type: object + properties: + self: + type: string + format: uri + description: The canonical API endpoint for this action. + example: 'https://api.osf.io/v2/actions/abc123/' diff --git a/swagger-spec/actions/node_request_action_list.yaml b/swagger-spec/actions/node_request_action_list.yaml new file mode 100644 index 0000000..fd475db --- /dev/null +++ b/swagger-spec/actions/node_request_action_list.yaml @@ -0,0 +1,176 @@ +# /actions/requests/nodes/: + +post: + summary: Create a Node Request Action + description: >- + Create a new action on an existing Node Request. + + Node Request Actions represent state transitions or comments on node-related requests, + such as access or withdrawal requests. Actions document and facilitate moderation workflows + for node requests managed through the OSF. + + ## Available Triggers + + Supported triggers for Node Request Actions include: + - `submit`: Submit or resubmit the node request for review. No special permissions required. + - `accept`: Approve the node request. Requires admin permissions. + - `reject`: Reject the node request. Requires admin permissions. + - `edit_comment`: Add or update a comment without changing the request’s state. Requires admin permissions. + + #### Request Format + + This endpoint expects a JSON:API compliant payload structured as follows: + + ```json + { + "data": { + "type": "node-request-actions", + "attributes": { + "trigger": "accept", + "comment": "Approving the node access request." + }, + "relationships": { + "target": { + "data": { + "type": "node-requests", + "id": "nodeReq123" + } + } + } + } + } + ``` + + #### Permissions + + Permission checks are enforced based on the trigger: + - Actions like `accept`, `reject`, and `edit_comment` require admin permissions on the target node. + + #### Returns + + On success, returns a `201 Created` response with a `data` object representing the newly created + Node Request Action. + + #### Errors + + Possible errors include: + + - `400 Bad Request`: Invalid payload or missing required fields. + - `403 Forbidden`: Insufficient permissions to perform the requested action. + - `409 Conflict`: The trigger is invalid for the node request’s current state. + + Refer to [Errors and Error Codes](#tag/Errors-and-Error-Codes) for more details. + + tags: + - Actions + + operationId: node_request_action_create + + consumes: + - application/json + produces: + - application/json + + parameters: + - in: body + name: body + required: true + description: >- + A JSON:API payload describing the Node Request Action to create. + schema: + type: object + properties: + data: + type: object + required: + - type + - attributes + - relationships + properties: + type: + type: string + example: node-request-actions + attributes: + type: object + required: + - trigger + properties: + trigger: + type: string + example: accept + comment: + type: string + example: "Approved node request." + relationships: + type: object + required: + - target + properties: + target: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + example: node-requests + id: + type: string + example: nodeReq123 + + responses: + '201': + description: Node Request Action successfully created. + schema: + type: object + examples: + application/json: + data: + id: nodeAction123 + type: node-request-actions + attributes: + trigger: accept + comment: "Approved node request." + from_state: pending + to_state: accepted + date_created: '2024-03-13T15:30:00Z' + date_modified: '2024-03-13T15:30:00Z' + auto: false + visible: true + relationships: + creator: + links: + related: + href: 'https://api.osf.io/v2/users/user456/' + meta: {} + data: + id: user456 + type: users + target: + links: + related: + href: 'https://api.osf.io/v2/requests/nodes/nodeReq123/' + meta: {} + data: + id: nodeReq123 + type: node-requests + links: + self: 'https://api.osf.io/v2/actions/nodeAction123/' + + '400': + description: >- + Bad request. The payload is invalid or missing required fields. + + '403': + description: >- + Forbidden. You do not have permission to perform this action. + + '409': + description: >- + Conflict. Invalid state transition for the given trigger. diff --git a/swagger-spec/actions/preprint_request_action_list.yaml b/swagger-spec/actions/preprint_request_action_list.yaml new file mode 100644 index 0000000..b0b000c --- /dev/null +++ b/swagger-spec/actions/preprint_request_action_list.yaml @@ -0,0 +1,211 @@ +# /actions/requests/preprints/: +post: + summary: Create a Preprint Request Action + description: >- + Create a new action on an existing Preprint Request. + + Preprint Request Actions represent state changes or comments on preprint-related requests, + such as requests for access or withdrawal. Actions document and facilitate moderation workflows + for preprints submitted through the OSF. + + #### Available Triggers + + Preprint Request Actions support the following triggers: + + - `submit`: Submit the request for review or re-submit after changes. + - `accept`: Approve the request (e.g., approve withdrawal). + - `reject`: Reject the request. + - `edit_comment`: Update or add a comment without altering the request’s state. + + #### Request Format + + The request payload must follow the [JSON:API specification](https://jsonapi.org/), structured as: + + ```json + { + "data": { + "type": "preprint-request-actions", + "attributes": { + "trigger": "accept", + "comment": "Approving the preprint withdrawal request." + }, + "relationships": { + "target": { + "data": { + "type": "preprint-requests", + "id": "preprintReq123" + } + } + } + } + ``` + + #### Returns + + On success, returns a `201 Created` response with the newly created Preprint Request Action. + + #### Errors + + Errors return an `errors` object describing the failure: + + - `400 Bad Request`: Payload is invalid or missing required fields. + - `403 Forbidden`: Insufficient permissions to perform the action. + - `409 Conflict`: Invalid state transition. + + Refer to [Errors and Error Codes](#tag/Errors-and-Error-Codes) for more details. + + tags: + - Actions + operationId: preprint_request_action_create + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + required: true + description: A JSON:API representation of the Preprint Request Action to create. + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - attributes + - relationships + properties: + type: + type: string + example: preprint-request-actions + attributes: + type: object + required: + - trigger + properties: + trigger: + type: string + example: accept + comment: + type: string + example: "Approving the preprint withdrawal request." + relationships: + type: object + required: + - target + properties: + target: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + example: preprint-requests + id: + type: string + example: preprintReq123 + responses: + '201': + description: Preprint Request Action successfully created. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: preprintAction123 + type: + type: string + example: preprint-request-actions + attributes: + type: object + properties: + trigger: + type: string + example: accept + comment: + type: string + example: "Approved preprint withdrawal request." + from_state: + type: string + example: pending + to_state: + type: string + example: accepted + date_created: + type: string + format: date-time + example: '2024-03-13T15:30:00Z' + date_modified: + type: string + format: date-time + example: '2024-03-13T15:30:00Z' + auto: + type: boolean + example: false + visible: + type: boolean + example: true + relationships: + type: object + properties: + creator: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: 'https://api.osf.io/v2/users/user456/' + data: + type: object + properties: + id: + type: string + example: user456 + type: + type: string + example: users + target: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: 'https://api.osf.io/v2/requests/preprints/preprintReq123/' + data: + type: object + properties: + id: + type: string + example: preprintReq123 + type: + type: string + example: preprint-requests + links: + type: object + properties: + self: + type: string + example: 'https://api.osf.io/v2/actions/preprintAction123/' + '400': + description: Bad request. The request payload is invalid or incomplete. + '403': + description: Permission denied. + '409': + description: Conflict due to invalid state transition. diff --git a/swagger-spec/actions/review_action_list.yaml b/swagger-spec/actions/review_action_list.yaml new file mode 100644 index 0000000..eadbb1e --- /dev/null +++ b/swagger-spec/actions/review_action_list.yaml @@ -0,0 +1,167 @@ +# /actions/reviews/: + +get: + summary: List Review Actions + description: >- + Retrieve a list of review actions visible to the authenticated user. + + Review actions represent state transitions or comments made on reviewable objects, such as preprints. + This endpoint returns all review actions the user is authorized to view. + + #### Filtering & Pagination + + Supports pagination and filtering by `id`, `trigger`, `from_state`, `to_state`, `date_created`, and `date_modified`. + + #### Returns + + A JSON object containing an array of review actions under the `data` key. + + #### Errors + + Returns an `errors` object if unsuccessful. See [Errors and Error Codes](#tag/Errors-and-Error-Codes). + + tags: + - Actions + operationId: review_action_list + produces: + - application/json + responses: + '200': + description: Successful retrieval of review actions. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: reviewAction123 + type: + type: string + example: review-actions + attributes: + type: object + properties: + trigger: + type: string + example: accept + comment: + type: string + example: "This looks great!" + from_state: + type: string + example: pending + to_state: + type: string + example: accepted + date_created: + type: string + format: date-time + example: '2024-03-14T10:00:00Z' + date_modified: + type: string + format: date-time + example: '2024-03-14T10:05:00Z' + auto: + type: boolean + example: false + visible: + type: boolean + example: true + relationships: + type: object + properties: + creator: + type: object + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: 'https://api.osf.io/v2/users/user456/' + meta: + type: object + data: + type: object + properties: + id: + type: string + example: user456 + type: + type: string + example: users + target: + type: object + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: 'https://api.osf.io/v2/preprints/xyz789/' + meta: + type: object + data: + type: object + properties: + id: + type: string + example: xyz789 + type: + type: string + example: preprints + provider: + type: object + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: 'https://api.osf.io/v2/providers/osf/' + meta: + type: object + data: + type: object + properties: + id: + type: string + example: osf + type: + type: string + example: providers + meta: + type: object + properties: + total: + type: integer + example: 1 + per_page: + type: integer + example: 10 + version: + type: string + example: '2.20' + links: + type: object + properties: + self: + type: string + format: uri + example: 'https://api.osf.io/v2/actions/reviews/' diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 20ea459..0ce094f 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -33,6 +33,7 @@ x-tagGroups: - Entities & Entity Collections - name: API Reference tags: + - Actions - Addons - Base - Citations @@ -854,8 +855,41 @@ tags: adheres to the standards set for collection submissions. It aids in providing transparency and order to the process of managing collections and ensures that moderators and admins have the tools and information they need to effectively manage collection submissions. - - + - name: Actions + description: >- + Actions represent state transitions or comments performed on reviewable or request-related resources within the OSF platform, such as Preprints, Nodes, Preprint Requests, Node Requests, and Collection Submissions. These endpoints document and facilitate moderation and administrative workflows, ensuring transparency and accountability in managing user interactions, moderation processes, and lifecycle management for various resources. + Each Action captures: + + **State transitions**: Tracking the movement of resources through different states (e.g., from pending to accepted). + **Comments** : Optional explanations or notes added during an action to provide context or reasons for state transitions. + **Triggers** : Specific actions (`submit`, `accept`, `reject`, `withdraw`, `edit_comment`, etc.) that initiate state transitions. + **Metadata** : Information such as timestamps for creation and modification, visibility settings, and whether the action was automated. + + Actions are categorized based on their targets: + + - **Review Actions**: Pertaining to moderation and review processes on Preprints. + - **Node Request Actions**: Related to Node Requests (e.g., access or withdrawal requests). + - **Preprint Request Actions**: Related to Preprint Requests, such as withdrawal requests. + + Actions require specific permissions depending on their triggers: + - `submit`: Typically open, no special permissions required. + - `accept`/`reject`: Require moderation or admin permissions. + - `edit_comment`: Requires administrative permissions. + + Each successful action response returns a JSON:API formatted object containing: + - **id** : The identifier of the action. + - **type** : Type of action performed (e.g., `review-actions`, `node-request-actions`). + - **attributes** : Information including `trigger`, `comment`, `from_state`, `to_state`, timestamps (`date_created`, `date_modified`), visibility (`visible`), and automation flag (`auto`). + - **relationships** : + - `creator`: User who initiated the action. + - **target** : The resource the action applies to (e.g., Preprint, Node Request). + - **provider** : Provider associated with the target, if applicable. + + Actions may fail due to various reasons, resulting in standard error responses: + - `400 Bad Request`: Invalid or malformed payload. + - `403 Forbidden`: Insufficient permissions to perform the action. + - `404 Not Found`: The target resource does not exist or is inaccessible. + - `409 Conflict`: Invalid action due to the current state of the target resource. paths: @@ -1276,12 +1310,46 @@ paths: /users/{user_id}/addons/{provider}/accounts/{account_id}/: $ref: 'users/addon_account_detail.yaml' + /users/{user_id}/claim/: + $ref: 'users/user_claim.yaml' + + /users/{user_id}/draft_preprints/: + $ref: 'users/user_draft_preprints_list.yaml' + + /users/{user_id}/draft_registrations/: + $ref: 'users/user_draft_registrations_list.yaml' + + /users/{user_id}/relationships/institutions/: + $ref: 'users/user_relationships_institutions.yaml' + + /users/{user_id}/settings/: + $ref: 'users/user_settings.yaml' + + /users/{user_id}/settings/emails/: + $ref: 'users/user_settings_emails_list.yaml' + + /users/{user_id}/settings/emails/{email_id}/: + $ref: 'users/user_settings_email_detail.yaml' + + /users/{user_id}/settings/export/: + $ref: 'users/user_settings_export.yaml' + + /users/{user_id}/settings/identities/: + $ref: 'users/user_settings_identities_list.yaml' + + /users/{user_id}/settings/identities/{identity_id}: + $ref: 'users/user_settings_identities_detail.yaml' + + /users/{user_id}/settings/password/: + $ref: 'users/user_password.yaml' + ###################### # View Only Links # ###################### /view_only_links/{link_id}/: $ref: 'view_only_links/detail.yaml' + /view_only_links/{link_id}/nodes/: $ref: 'view_only_links/nodes.yaml' @@ -1376,3 +1444,19 @@ paths: /provider/collections/{collection_id}/moderators/{moderator_id}/: $ref: 'collection_provider/moderators_detail.yaml' + + ############################ + # ACTIONS # + ############################ + + /actions/reviews/: + $ref: 'actions/review_action_list.yaml' + + /actions/requests/nodes/: + $ref: 'actions/node_request_action_list.yaml' + + /actions/requests/preprints/: + $ref: 'actions/preprint_request_action_list.yaml' + + /actions/{action_id}/: + $ref: 'actions/action_detail.yaml' \ No newline at end of file diff --git a/swagger-spec/users/user_claim.yaml b/swagger-spec/users/user_claim.yaml new file mode 100644 index 0000000..333d60a --- /dev/null +++ b/swagger-spec/users/user_claim.yaml @@ -0,0 +1,101 @@ +# /users/{user_id}/claim/: + +post: + summary: Claim a User Account + description: >- + Allows a user to claim an unregistered OSF account. + + This endpoint is typically used when a contributor is added to a project with an unregistered account, + and the user wants to claim that account. + + The user can be claimed by either: + - A logged-in user (who is not the referrer of the unclaimed account). + - A user who provides an email address for the claim. + + #### Returns + + Returns a `204 No Content` response on successful claim initiation. + + #### Errors + + 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: + - `403 Forbidden`: The user is not authorized to claim this account. + - `404 Not Found`: The specified user or record does not exist. + - `400 Bad Request`: Invalid claim request parameters. + tags: + - Users + operationId: user_claim_create + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user you are trying to claim. + + Example: `abc123` + - in: body + name: body + required: true + description: >- + A JSON API representation of the claim request. + + You must provide at least a `record id`. Optionally, an `email` may be included if you are not authenticated. + schema: + type: object + properties: + data: + type: object + properties: + type: + type: string + enum: [claim-user] + example: claim-user + attributes: + type: object + properties: + id: + type: string + description: >- + The record ID associated with the unclaimed user. Usually corresponds to a project, preprint, etc. + example: xyz456 + email: + type: string + description: >- + The email address to use for claiming the user account. Required if the claimer is not authenticated. + example: user@example.com + required: + - data + x-examples: + application/json: + data: + type: claim-user + attributes: + id: xyz456 + email: user@example.com + responses: + '204': + description: >- + Successfully initiated the claim process. + + If the claimer is authenticated, they will receive an email confirming the claim. + If not authenticated and an email is provided, the claim invitation will be sent to the specified email address. + '400': + description: >- + Bad request. + + The request payload is invalid or missing required fields (such as `id`). + '403': + description: >- + Permission denied. + + You do not have permission to claim this user, or the user has already been claimed. + '404': + description: >- + Not found. + + The specified user or record could not be found. diff --git a/swagger-spec/users/user_draft_preprints_list.yaml b/swagger-spec/users/user_draft_preprints_list.yaml new file mode 100644 index 0000000..d8953c7 --- /dev/null +++ b/swagger-spec/users/user_draft_preprints_list.yaml @@ -0,0 +1,99 @@ +# /users/{user_id}/draft_preprints/: + +get: + summary: List a User's Draft Preprints + description: >- + Retrieves a list of draft preprints for the specified user. + + Only the authenticated user can view their own draft preprints. + + #### Returns + + Returns a JSON object with a `data` key containing an array of draft preprint resources. + + #### Errors + + 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). + + tags: + - Users + operationId: user_draft_preprints_list + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: "The unique identifier of the user. Example: `abc123`" + - in: query + name: page + type: integer + description: Page number of results to view (pagination). Default is 1. + - in: query + name: filter[title] + type: string + description: Filter draft preprints by title. + responses: + '200': + description: >- + Successfully retrieved the list of draft preprints. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + meta: + type: object + properties: + total: + type: integer + per_page: + type: integer + version: + type: string + links: + type: object + properties: + self: + type: string + next: + type: string + prev: + type: string + examples: + application/json: + data: + - id: draftpreprint123 + type: draft-preprints + attributes: + title: Draft Preprint Example + date_created: '2024-01-01T00:00:00Z' + date_modified: '2024-01-01T12:00:00Z' + preprint_provider: example-provider + relationships: + creator: + data: + id: abc123 + type: users + provider: + data: + id: example-provider + type: providers + meta: + total: 1 + per_page: 10 + version: '2.20' + links: + self: 'https://api.osf.io/v2/users/abc123/draft_preprints/' + next: null + prev: null + '403': + description: >- + Permission denied. You do not have permission to view these draft preprints. + '404': + description: >- + User not found. diff --git a/swagger-spec/users/user_draft_registrations_list.yaml b/swagger-spec/users/user_draft_registrations_list.yaml new file mode 100644 index 0000000..6abaaba --- /dev/null +++ b/swagger-spec/users/user_draft_registrations_list.yaml @@ -0,0 +1,99 @@ +# /users/{user_id}/draft_registrations/: + +get: + summary: List a User's Draft Registrations + description: >- + Retrieves a list of draft registrations for the specified user. + + Only the authenticated user can view their own draft registrations. + + #### Returns + + Returns a JSON object with a `data` key containing an array of draft registration resources. + + #### Errors + + 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). + + tags: + - Users + operationId: user_draft_registrations_list + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: "The unique identifier of the user. Example: `abc123`" + - in: query + name: page + type: integer + description: Page number of results to view (pagination). Default is 1. + - in: query + name: filter[title] + type: string + description: Filter draft registrations by title. + responses: + '200': + description: >- + Successfully retrieved the list of draft registrations. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + meta: + type: object + properties: + total: + type: integer + per_page: + type: integer + version: + type: string + links: + type: object + properties: + self: + type: string + next: + type: string + prev: + type: string + examples: + application/json: + data: + - id: draftreg123 + type: draft-registrations + attributes: + title: Draft Registration Example + date_created: '2024-01-01T00:00:00Z' + date_modified: '2024-01-01T12:00:00Z' + registration_metadata: {} + relationships: + creator: + data: + id: abc123 + type: users + branched_from: + data: + id: proj456 + type: nodes + meta: + total: 1 + per_page: 10 + version: '2.20' + links: + self: 'https://api.osf.io/v2/users/abc123/draft_registrations/' + next: null + prev: null + '403': + description: >- + Permission denied. You do not have permission to view these draft registrations. + '404': + description: >- + User not found. diff --git a/swagger-spec/users/user_password.yaml b/swagger-spec/users/user_password.yaml new file mode 100644 index 0000000..a145c2d --- /dev/null +++ b/swagger-spec/users/user_password.yaml @@ -0,0 +1,97 @@ +# /users/{user_id}/settings/password/: + +post: + summary: Change a User's Password + description: >- + Change the password for the specified user. + + Only the current authenticated user can change their own password using this endpoint. + + #### Returns + + Returns a `204 No Content` response if the password change was successful. + + #### Errors + + 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: + - `400 Bad Request`: Invalid or missing password fields. + - `403 Forbidden`: You are not authorized to change this user's password. + - `429 Too Many Requests`: Too many failed attempts; try again later. + tags: + - Users + operationId: user_password_change + consumes: + - application/json + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user whose password is being changed. + + Example: `abc123` + - in: body + name: body + required: true + description: >- + A JSON API representation of the password change request. + + You must provide both the existing password and the new password. + schema: + type: object + properties: + data: + type: object + properties: + type: + type: string + enum: [user_passwords] + example: user_passwords + attributes: + type: object + properties: + existing_password: + type: string + description: The user's current password. + example: current_password_123 + new_password: + type: string + description: The new password to set for the user. + example: new_secure_password_456 + required: + - data + x-examples: + application/json: + data: + type: user_passwords + attributes: + existing_password: current_password_123 + new_password: new_secure_password_456 + responses: + '204': + description: >- + Password successfully changed. + + All sessions for the user will be logged out and must be re-authenticated. + '400': + description: >- + Bad request. + + The existing password is incorrect, or the new password is invalid. + '403': + description: >- + Permission denied. + + You do not have permission to change this user's password. + '429': + description: >- + Too many failed attempts. + + Please wait before trying again. diff --git a/swagger-spec/users/user_relationships_institutions.yaml b/swagger-spec/users/user_relationships_institutions.yaml new file mode 100644 index 0000000..0298d81 --- /dev/null +++ b/swagger-spec/users/user_relationships_institutions.yaml @@ -0,0 +1,143 @@ +# /users/{user_id}/relationships/institutions/: + +get: + summary: Retrieve a User's Institution Relationships + description: >- + Retrieves the relationships between a user and their affiliated institutions. + + Only the authenticated user can view their affiliated institutions in this relationship endpoint. + + #### Returns + + Returns a JSON object with a `data` key containing an array of institution relationship identifiers. + + #### Errors + + 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). + tags: + - Users + operationId: user_institutions_relationship_read + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: "The unique identifier of the user. Example: `abc123`" + responses: + '200': + description: >- + Successfully retrieved the user's affiliated institutions. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + description: The institution ID. + example: mit + type: + type: string + description: Resource type. + example: institutions + examples: + application/json: + data: + - id: mit + type: institutions + - id: cambridge + type: institutions + '403': + description: >- + Permission denied. You do not have permission to view these institution relationships. + '404': + description: >- + User not found. + + +delete: + summary: Remove Institutions from a User's Affiliations + description: >- + Removes one or more institutions from a user's list of affiliations. + + #### Usage Notes + + - Only the authenticated user can remove their institution affiliations. + - You cannot add institutions through this endpoint—use the user-institutions list endpoint for reading full records. + + #### Returns + + Returns a `204 No Content` response if the removal is successful. + + #### Errors + + 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). + + #### Example Request Payload + + ```json + { + "data": [ + { "type": "institutions", "id": "mit" }, + { "type": "institutions", "id": "cambridge" } + ] + } + ``` + tags: + - Users + operationId: user_institutions_relationship_delete + consumes: + - application/json + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: "The unique identifier of the user. Example: `abc123`" + - in: body + name: body + required: true + description: List of institution relationships to remove. + schema: + type: object + required: + - data + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: [institutions] + id: + type: string + example: mit + responses: + '204': + description: >- + Successfully removed institutions from user's affiliations. + '400': + description: >- + Bad request. Possible reasons include: + - Institution `type` does not match `institutions`. + - Institution ID is invalid or not affiliated with the user. + '403': + description: >- + Permission denied. You do not have permission to modify these affiliations. + '404': + description: >- + User not found. diff --git a/swagger-spec/users/user_settings.yaml b/swagger-spec/users/user_settings.yaml new file mode 100644 index 0000000..2771dc6 --- /dev/null +++ b/swagger-spec/users/user_settings.yaml @@ -0,0 +1,156 @@ +# /users/{user_id}/settings/: + +get: + summary: Retrieve a User's Settings + description: >- + Retrieves a user's settings, including two-factor authentication status, email subscriptions, and deactivation status. + + Only the authenticated user can access their settings. + + #### Returns + + Returns a JSON object with a `data` key containing the user's settings. + + #### Errors + + 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). + tags: + - Users + operationId: user_settings_read + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user. + + Example: `abc123` + responses: + '200': + description: >- + Successfully retrieved the user's settings. + examples: + application/json: + data: + id: abc123 + type: user-settings + attributes: + two_factor_enabled: true + two_factor_confirmed: true + subscribe_osf_general_email: true + subscribe_osf_help_email: false + deactivation_requested: false + contacted_deactivation: false + '403': + description: >- + Permission denied. You do not have permission to view these settings. + + +patch: + summary: Update a User's Settings + description: >- + Updates a user's settings, including email subscriptions, two-factor authentication setup, and account deactivation status. + + Only the authenticated user can modify their settings. + + ## Editable Attributes + + - `two_factor_enabled` (boolean): Enables or disables two-factor authentication. + - `two_factor_verification` (integer): Verification code for two-factor setup. + - `subscribe_osf_general_email` (boolean): Subscribe/unsubscribe from OSF general communications. + - `subscribe_osf_help_email` (boolean): Subscribe/unsubscribe from OSF help communications. + - `deactivation_requested` (boolean): Request deactivation of your OSF account. + + #### Returns + + Returns the updated user's settings in a JSON object with a `data` key. + + #### Errors + + 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). + tags: + - Users + operationId: user_settings_update + consumes: + - application/json + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user. + + Example: `abc123` + - in: body + name: body + required: true + description: JSON API representation of the updates to the user's settings. + schema: + type: object + properties: + data: + type: object + properties: + type: + type: string + enum: [user-settings] + example: user-settings + id: + type: string + description: The user ID for the settings update. + example: abc123 + attributes: + type: object + properties: + two_factor_enabled: + type: boolean + description: Enable or disable two-factor authentication. + example: true + two_factor_verification: + type: integer + description: Verification code for two-factor authentication. + example: 123456 + subscribe_osf_general_email: + type: boolean + description: Subscribe or unsubscribe from OSF general emails. + example: true + subscribe_osf_help_email: + type: boolean + description: Subscribe or unsubscribe from OSF help emails. + example: false + deactivation_requested: + type: boolean + description: Request deactivation of your OSF account. + example: false + x-examples: + application/json: + data: + type: user-settings + id: abc123 + attributes: + two_factor_enabled: true + two_factor_verification: 123456 + subscribe_osf_general_email: true + subscribe_osf_help_email: false + deactivation_requested: false + responses: + '200': + description: >- + Successfully updated the user's settings. + '400': + description: >- + Bad request. This can occur if the two-factor verification code is invalid, or subscription values are incorrect. + '403': + description: >- + Permission denied. You do not have permission to update these settings. + '404': + description: >- + User not found. diff --git a/swagger-spec/users/user_settings_definition.yaml b/swagger-spec/users/user_settings_definition.yaml new file mode 100644 index 0000000..b33b935 --- /dev/null +++ b/swagger-spec/users/user_settings_definition.yaml @@ -0,0 +1,38 @@ +UserSettings: + type: object + properties: + id: + type: string + description: The unique identifier of the user. + example: abc123 + type: + type: string + description: Resource type. + example: user-settings + attributes: + type: object + properties: + two_factor_enabled: + type: boolean + description: Whether two-factor authentication is enabled. + example: true + two_factor_confirmed: + type: boolean + description: Whether two-factor authentication is confirmed. + example: true + subscribe_osf_general_email: + type: boolean + description: Whether the user is subscribed to OSF general emails. + example: true + subscribe_osf_help_email: + type: boolean + description: Whether the user is subscribed to OSF help emails. + example: false + deactivation_requested: + type: boolean + description: Whether the user has requested deactivation of their account. + example: false + contacted_deactivation: + type: boolean + description: Whether the OSF support team has contacted the user about deactivation. + example: false diff --git a/swagger-spec/users/user_settings_email_detail.yaml b/swagger-spec/users/user_settings_email_detail.yaml new file mode 100644 index 0000000..277f5de --- /dev/null +++ b/swagger-spec/users/user_settings_email_detail.yaml @@ -0,0 +1,200 @@ +# /users/{user_id}/settings/emails/{email_id}/: +get: + summary: Retrieve a User's Email Address + description: >- + Retrieves detailed information about a specific email address linked to the user. + + Only the authenticated user can view their own email addresses. + + #### Query Parameters + + - `resend_confirmation=true` -- Optional. If the email address is unconfirmed, this query param will resend the confirmation email. + + #### Returns + + Returns a JSON object with a `data` key containing the details of the requested email address. + + #### Errors + + 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. + tags: + - Users + operationId: user_email_detail_read + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: "The unique identifier of the user. Example: `abc123`" + - in: path + name: email_id + required: true + type: string + description: >- + The unique identifier of the email address (either a hashed ID or unconfirmed token). Example: `1a2b3c` + - in: query + name: resend_confirmation + required: false + type: boolean + description: >- + If true, resend a confirmation email to the unconfirmed address (if applicable). + responses: + '200': + description: >- + Successfully retrieved the email address. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: 1a2b3c + type: user-emails + attributes: + email_address: user@example.com + confirmed: true + verified: true + primary: true + is_merge: false + '403': + description: >- + Permission denied. You do not have permission to view this email. + '404': + description: >- + Email address not found. + + +patch: + summary: Update a User's Email Address + description: >- + Updates attributes of a user's email address. + + #### Allowed Updates + + - Set an email address as `primary` (must already be confirmed). + - Mark an email as `verified` (must already be confirmed). + + #### Returns + + Returns the updated email address in a JSON object with a `data` key. + + #### Errors + + 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). + tags: + - Users + operationId: user_email_detail_update + consumes: + - application/json + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: "The unique identifier of the user. Example: `abc123`" + - in: path + name: email_id + required: true + type: string + description: "The unique identifier of the email address. Example: `1a2b3c`" + - in: body + name: body + required: true + description: JSON API representation of the updates to the email address. + schema: + type: object + properties: + data: + type: object + properties: + type: + type: string + enum: [user-emails] + example: user-emails + id: + type: string + description: "The email ID to update. Example: `1a2b3c`" + attributes: + type: object + properties: + primary: + type: boolean + description: Whether this email should be set as primary. + verified: + type: boolean + description: Whether this email should be marked as verified (requires confirmation first). + x-examples: + application/json: + data: + type: user-emails + id: 1a2b3c + attributes: + primary: true + responses: + '200': + description: >- + Successfully updated the email address. + schema: + $ref: 'definition.yaml' + '400': + description: >- + Bad request. This can occur if trying to set an unconfirmed email as primary or verify an unconfirmed email. + '403': + description: >- + Permission denied. + '404': + description: >- + Email address not found. + + +delete: + summary: Remove a User's Email Address + description: >- + Deletes an email address from the user's account. + + - If the email is confirmed and verified, it will be removed. + - If the email is unconfirmed, it will be removed from unconfirmed emails. + - Cannot delete the primary email address. + + #### Returns + + Returns a `204 No Content` response if the email was successfully removed. + + #### Errors + + 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). + tags: + - Users + operationId: user_email_detail_delete + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: "The unique identifier of the user. Example: `abc123`" + - in: path + name: email_id + required: true + type: string + description: "The unique identifier of the email address. Example: `1a2b3c`" + responses: + '204': + description: >- + Email address successfully removed. + '400': + description: >- + Bad request. Cannot delete the primary email address. + '403': + description: >- + Permission denied. + '404': + description: >- + Email address not found. diff --git a/swagger-spec/users/user_settings_emails_list.yaml b/swagger-spec/users/user_settings_emails_list.yaml new file mode 100644 index 0000000..2ea1e8e --- /dev/null +++ b/swagger-spec/users/user_settings_emails_list.yaml @@ -0,0 +1,165 @@ +# /users/{user_id}/settings/emails/: + +get: + summary: List User Email Addresses + description: >- + Retrieves a list of all confirmed and unconfirmed email addresses associated with the user. + + The authenticated user can view their own email addresses. + + #### Returns + + Returns a JSON object with a `data` key containing a list of email addresses associated with the user. + + #### Errors + + 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. + tags: + - Users + operationId: user_emails_list + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user whose emails are being listed. + + Example: `abc123` + responses: + '200': + description: >- + A list of confirmed and unconfirmed email addresses for the user. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + examples: + application/json: + data: + - id: 1a2b3c + type: user-emails + attributes: + email_address: user@example.com + confirmed: true + verified: true + primary: true + is_merge: false + - id: unconfirmed_token + type: user-emails + attributes: + email_address: another@example.com + confirmed: false + verified: false + primary: false + is_merge: false + '403': + description: >- + Permission denied. + + You do not have permission to view email addresses for this user. + + +post: + summary: Add a New Email Address + description: >- + Adds a new unconfirmed email address to the user's account. + + Once added, the system will send a confirmation email to the specified address. + + #### Returns + + Returns a JSON object with a `data` key containing the newly added (unconfirmed) email address. + + #### Errors + + 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. + tags: + - Users + operationId: user_email_create + consumes: + - application/json + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user to whom the email will be added. + + Example: `abc123` + - in: body + name: body + required: true + description: >- + A JSON API representation of the new email address to add. + + You must provide an `email_address` in the attributes object. + schema: + type: object + properties: + data: + type: object + properties: + type: + type: string + enum: [user-emails] + example: user-emails + attributes: + type: object + properties: + email_address: + type: string + description: The new email address to add. + example: newemail@example.com + required: + - data + x-examples: + application/json: + data: + type: user-emails + attributes: + email_address: newemail@example.com + responses: + '201': + description: >- + The email address was successfully added and is pending confirmation. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: unconfirmed_token_123 + type: user-emails + attributes: + email_address: newemail@example.com + confirmed: false + verified: false + primary: false + is_merge: false + '400': + description: >- + Bad request. + + The email address is invalid or already exists on this user. + '403': + description: >- + Permission denied. + + You do not have permission to add an email for this user. + '429': + description: >- + Too many requests. + + You have exceeded the allowed number of email additions. Please wait and try again later. diff --git a/swagger-spec/users/user_settings_export.yaml b/swagger-spec/users/user_settings_export.yaml new file mode 100644 index 0000000..de2a467 --- /dev/null +++ b/swagger-spec/users/user_settings_export.yaml @@ -0,0 +1,78 @@ +# /users/{user_id}/settings/export/: + +post: + summary: Request User Account Export + description: >- + Initiates an export of the user's account data. + + This endpoint triggers an email to OSF support requesting an export of the user's account data. + Only the authenticated user can request their own account export. + + ## Returns + + Returns a `204 No Content` response if the export request was successfully submitted. + + ## Errors + + 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: + - `403 Forbidden`: You do not have permission to request an export for this user. + - `429 Too Many Requests`: Export requests are throttled. You may need to wait before trying again. + tags: + - Users + operationId: user_account_export_create + consumes: + - application/json + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user requesting the export. + + Example: `abc123` + - in: body + name: body + required: true + description: >- + A JSON API representation of the export request. + + No additional attributes are required in the request payload. + schema: + type: object + properties: + data: + type: object + properties: + type: + type: string + enum: [user-account-export-form] + example: user-account-export-form + required: + - data + x-examples: + application/json: + data: + type: user-account-export-form + responses: + '204': + description: >- + Export request successfully submitted. + + The user will receive confirmation once the export process is completed. + '403': + description: >- + Permission denied. + + You do not have permission to request an export for this user. + '429': + description: >- + Too many requests. + + You have exceeded the allowed number of export requests. Please wait and try again later. diff --git a/swagger-spec/users/user_settings_identities_detail.yaml b/swagger-spec/users/user_settings_identities_detail.yaml new file mode 100644 index 0000000..98de838 --- /dev/null +++ b/swagger-spec/users/user_settings_identities_detail.yaml @@ -0,0 +1,118 @@ +# /users/{user_id}/settings/identities/{identity_id}/: + +get: + summary: Retrieve a User's External Identity + description: >- + Retrieves detailed information about a single external identity linked to the user. + + External identities represent accounts linked from external services or identity providers (e.g., ORCID, institutions). + + Only the authenticated user can view their own external identities. + + #### Returns + + Returns a JSON object with a `data` key containing the details of the requested external identity. + + #### Errors + + 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. + tags: + - Users + operationId: user_identity_detail_read + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user whose external identity is being retrieved. + + Example: `abc123` + - in: path + name: identity_id + required: true + type: string + description: >- + The unique identifier of the external identity to retrieve. + + Example: `orcid` + responses: + '200': + description: >- + A single external identity for the user. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: orcid + type: external-identities + attributes: + external_id: 0000-0002-1825-0097 + status: VERIFIED + '403': + description: >- + Permission denied. + + You do not have permission to view external identities for this user. + '404': + description: >- + External identity not found. + + No identity with the given ID exists for this user. + +delete: + summary: Remove a User's External Identity + description: >- + Deletes (removes) an external identity from the user's account. + + Only the authenticated user can delete their own external identities. + + #### Returns + + Returns a `204 No Content` response if the external identity was successfully removed. + + #### Errors + + 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. + tags: + - Users + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user whose external identity is being deleted. + + Example: `abc123` + - in: path + name: identity_id + required: true + type: string + description: >- + The unique identifier of the external identity to delete. + + Example: `orcid` + responses: + '204': + description: >- + External identity successfully removed. + '403': + description: >- + Permission denied. + + You do not have permission to remove external identities for this user. + '404': + description: >- + External identity not found. + + No identity with the given ID exists for this user. diff --git a/swagger-spec/users/user_settings_identities_list.yaml b/swagger-spec/users/user_settings_identities_list.yaml new file mode 100644 index 0000000..e4f6074 --- /dev/null +++ b/swagger-spec/users/user_settings_identities_list.yaml @@ -0,0 +1,63 @@ +# /users/{user_id}/settings/identities/: + +get: + summary: List User External Identities + description: >- + Retrieves a list of external identities connected to the user. + + External identities represent accounts linked from external services or identity providers (e.g., ORCID, institutions). + + Only the authenticated user can view their own external identities. + + #### Returns + + Returns a JSON object with a `data` key containing a list of external identities associated with the user. + + #### Errors + + 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. + tags: + - Users + operationId: user_identities_list + produces: + - application/json + parameters: + - in: path + name: user_id + required: true + type: string + description: >- + The unique identifier of the user whose external identities are being listed. + + Example: `abc123` + responses: + '200': + description: >- + A list of external identities associated with the user. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + examples: + application/json: + data: + - id: orcid + type: external-identities + attributes: + external_id: 0000-0002-1825-0097 + status: VERIFIED + - id: institution-abc + type: external-identities + attributes: + external_id: example-university.edu + status: LINKED + '403': + description: >- + Permission denied. + + You do not have permission to view external identities for this user. From ca1c6ac8effb7ed41c7d0a8e66927c655e360efe Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Fri, 14 Mar 2025 10:58:36 -0400 Subject: [PATCH 03/21] add region --- swagger-spec/region/region_detail.yaml | 66 ++++++++++++++++++++++++++ swagger-spec/region/region_list.yaml | 65 +++++++++++++++++++++++++ swagger-spec/swagger.yaml | 26 ++++++++++ 3 files changed, 157 insertions(+) create mode 100644 swagger-spec/region/region_detail.yaml create mode 100644 swagger-spec/region/region_list.yaml diff --git a/swagger-spec/region/region_detail.yaml b/swagger-spec/region/region_detail.yaml new file mode 100644 index 0000000..984e6b1 --- /dev/null +++ b/swagger-spec/region/region_detail.yaml @@ -0,0 +1,66 @@ +# /regions/{region_id}/: + +get: + summary: Region Detail + description: >- + Retrieves detailed information for a specific storage region identified by `{region_id}`. + + A storage region defines the geographical or cloud-based location used by OSF Storage for storing files. + + ## Returns + A JSON:API-compliant response containing a single `region` entity under the `data` key. + + ## Errors + Returns an `errors` object if unsuccessful: + - `404 Not Found`: No region matches the provided `region_id`. + tags: + - Regions + operationId: region_detail + produces: + - application/json + parameters: + - name: region_id + in: path + description: The unique identifier for the region. + required: true + type: string + responses: + '200': + description: Successfully retrieved region details. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: us-east-1 + type: + type: string + example: regions + attributes: + type: object + properties: + name: + type: string + example: US East + links: + type: object + properties: + self: + type: string + example: 'https://api.osf.io/v2/regions/us-east-1/' + '404': + description: Region not found. + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + detail: + type: string + example: 'No region matching that region_id could be found.' diff --git a/swagger-spec/region/region_list.yaml b/swagger-spec/region/region_list.yaml new file mode 100644 index 0000000..ef18b71 --- /dev/null +++ b/swagger-spec/region/region_list.yaml @@ -0,0 +1,65 @@ +# /regions/: + +get: + summary: List Regions + description: >- + Retrieves a list of available storage regions within OSF. + + Regions define geographical or cloud storage locations for storing files uploaded through OSF Storage. + + ## Returns + A JSON:API-compliant response containing an array of regions under the `data` key, including region attributes such as `id` and `name`. + + Supports standard pagination and sorting by name. + + ## Errors + If unsuccessful, returns an `errors` object. Refer to the [Errors and Error Codes](#tag/Errors-and-Error-Codes) section for details. + tags: + - Regions + operationId: region_list + produces: + - application/json + responses: + '200': + description: Successfully retrieved the list of regions. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: us-east-1 + type: + type: string + example: regions + attributes: + type: object + properties: + name: + type: string + example: US East + links: + type: object + properties: + self: + type: string + example: 'https://api.osf.io/v2/regions/us-east-1/' + meta: + type: object + properties: + total: + type: integer + example: 1 + per_page: + type: integer + example: 10 + links: + type: object + properties: + self: + type: string + example: 'https://api.osf.io/v2/regions/' diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 20ea459..1688a08 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -54,6 +54,7 @@ x-tagGroups: - Preprint Providers - Draft Registrations - Registrations + - Regions - Taxonomies - Users - View Only Links @@ -854,6 +855,20 @@ tags: adheres to the standards set for collection submissions. It aids in providing transparency and order to the process of managing collections and ensures that moderators and admins have the tools and information they need to effectively manage collection submissions. + - name: Regions + description: >- + Storage Regions are predefined geographical or cloud-storage areas where files are stored within OSF Storage. + + Each region provides isolation of data in compliance with geographic or regulatory requirements. Users can specify their preferred region for storing project files when using OSF Storage. + + **Attributes include:** + + - `id`: Unique identifier of the region (e.g., `us-east-1`). + - `name`: Human-readable name for the region (e.g., `US East`). + + **Endpoints include:** + - **List Regions:** Retrieve all available storage regions. + - **Region Detail:** Retrieve details about a specific storage region. @@ -1376,3 +1391,14 @@ paths: /provider/collections/{collection_id}/moderators/{moderator_id}/: $ref: 'collection_provider/moderators_detail.yaml' + + ####################################### + # REGIONS # + ####################################### + + /regions/: + $ref: 'region/region_list.yaml' + + /regions/{region_id}/: + $ref: 'region/region_detail.yaml' + From c41145c82089e94e186f3ab0562248dbf4f82af5 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Fri, 14 Mar 2025 11:14:34 -0400 Subject: [PATCH 04/21] add tokens --- swagger-spec/swagger.yaml | 20 ++- swagger-spec/tokens/detail.yaml | 1 - swagger-spec/tokens/list.yaml | 1 - swagger-spec/tokens/token_detail.yaml | 85 +++++++++++ swagger-spec/tokens/token_list.yaml | 170 +++++++++++++++++++++ swagger-spec/tokens/token_scopes_list.yaml | 51 +++++++ 6 files changed, 324 insertions(+), 4 deletions(-) delete mode 100644 swagger-spec/tokens/detail.yaml delete mode 100644 swagger-spec/tokens/list.yaml create mode 100644 swagger-spec/tokens/token_detail.yaml create mode 100644 swagger-spec/tokens/token_list.yaml create mode 100644 swagger-spec/tokens/token_scopes_list.yaml diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 1688a08..def7e93 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -56,6 +56,7 @@ x-tagGroups: - Registrations - Regions - Taxonomies + - Tokens - Users - View Only Links tags: @@ -869,8 +870,11 @@ tags: **Endpoints include:** - **List Regions:** Retrieve all available storage regions. - **Region Detail:** Retrieve details about a specific storage region. - - + - name: Tokens + description: >- + **Personal Access Tokens** allow users to authenticate API requests without credentials. + + Tokens support fine-grained permissions (scopes) to control API access levels. paths: @@ -1402,3 +1406,15 @@ paths: /regions/{region_id}/: $ref: 'region/region_detail.yaml' + ############################ + # TOKENS # + ############################ + + /tokens/: + $ref: 'tokens/token_list.yaml' + + /tokens/{_id}/: + $ref: 'tokens/token_detail.yaml' + + /tokens/{_id}/scopes/: + $ref: 'tokens/token_scopes_list.yaml' diff --git a/swagger-spec/tokens/detail.yaml b/swagger-spec/tokens/detail.yaml deleted file mode 100644 index 2735eae..0000000 --- a/swagger-spec/tokens/detail.yaml +++ /dev/null @@ -1 +0,0 @@ -# /tokens/{_id}/ diff --git a/swagger-spec/tokens/list.yaml b/swagger-spec/tokens/list.yaml deleted file mode 100644 index 7ffeb57..0000000 --- a/swagger-spec/tokens/list.yaml +++ /dev/null @@ -1 +0,0 @@ -# /tokens/ diff --git a/swagger-spec/tokens/token_detail.yaml b/swagger-spec/tokens/token_detail.yaml new file mode 100644 index 0000000..c9626d1 --- /dev/null +++ b/swagger-spec/tokens/token_detail.yaml @@ -0,0 +1,85 @@ +# /tokens/{_id}/: + +get: + summary: Personal Access Token Detail + description: >- + Retrieve details of a specific personal access token. + + #### Returns + A JSON:API-compliant response with the token's details. + + #### Errors + - `404 Not Found`: Token not found or not owned by the user. + + tags: + - Tokens + operationId: token_detail + produces: + - application/json + parameters: + - name: _id + in: path + required: true + type: string + description: The tokens's unique identifier. + responses: + '200': + description: Successful retrieval of tokens details. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: token123 + type: + type: string + example: tokens + attributes: + type: object + properties: + name: + type: string + example: "My API Token" + date_created: + type: string + format: date-time + example: "2024-03-14T15:00:00Z" + relationships: + type: object + properties: + scopes: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/tokens/token123/scopes/" + '404': + description: Token not found. + +delete: + summary: Deactivate Personal Access Token + description: >- + Deactivate (revoke) a personal access token. The token becomes inactive but is retained in the database. + + #### Errors + - `404 Not Found`: Token does not exist or is not accessible. + + tags: + - Tokens + operationId: token_deactivate + parameters: + - name: _id + in: path + required: true + type: string + description: The tokens's unique identifier. + responses: + '204': + description: Token successfully deactivated. + diff --git a/swagger-spec/tokens/token_list.yaml b/swagger-spec/tokens/token_list.yaml new file mode 100644 index 0000000..54d8219 --- /dev/null +++ b/swagger-spec/tokens/token_list.yaml @@ -0,0 +1,170 @@ +# /tokens/: + +get: + summary: List Personal Access Tokens + description: >- + Retrieve a list of active personal access tokens created by the authenticated user. + + Personal access tokens are used to authenticate requests to the OSF API without user credentials. + + #### Returns + A JSON:API-compliant response with an array of personal access token objects under the `data` key. + + #### Errors + Returns an `errors` object on failure. See [Errors and Error Codes](#tag/Errors-and-Error-Codes). + + tags: + - Tokens + operationId: token_list + produces: + - application/json + responses: + '200': + description: Successful retrieval of personal access tokens. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: token123 + type: + type: string + example: tokens + attributes: + type: object + properties: + name: + type: string + example: "My API Token" + date_created: + type: string + format: date-time + example: "2024-03-14T15:00:00Z" + relationships: + type: object + properties: + scopes: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/tokens/token123/scopes/" + meta: + type: object + properties: + total: + type: integer + example: 1 + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/tokens/" + +post: + summary: Create Personal Access Token + description: >- + Create a new personal access token for authenticating API requests. + + #### Request Body + A JSON:API-compliant request with token attributes (`name`) and `scopes` as relationships. + + #### Returns + A `201 Created` response with the newly created token details, including the token itself (`token_id`). + + **Note:** The token (`token_id`) is returned **only once** during creation. + + #### Errors + - `400 Bad Request`: Missing required fields or invalid scope. + - `403 Forbidden`: User lacks permission to create tokens. + + tags: + - Tokens + operationId: token_create + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: object + required: [type, attributes, relationships] + properties: + type: + type: string + example: tokens + attributes: + type: object + properties: + name: + type: string + example: "My API Token" + relationships: + type: object + properties: + scopes: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: scopes + id: + type: string + example: "osf.full_write" + + responses: + '201': + description: Token successfully created. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: token123 + type: + type: string + example: tokens + attributes: + type: object + properties: + name: + type: string + example: "My API Token" + token_id: + type: string + example: "abc123def456" + relationships: + type: object + properties: + scopes: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/tokens/token123/scopes/" diff --git a/swagger-spec/tokens/token_scopes_list.yaml b/swagger-spec/tokens/token_scopes_list.yaml new file mode 100644 index 0000000..238a112 --- /dev/null +++ b/swagger-spec/tokens/token_scopes_list.yaml @@ -0,0 +1,51 @@ +# /tokens/{_id}/scopes/: + +get: + summary: List Scopes of a Personal Access Token + description: >- + Retrieve the scopes associated with a specific personal access token. + + Scopes determine the level of access and operations permitted by the token. + + #### Returns + A JSON:API-compliant response containing an array of scopes. + + #### Errors + - `404 Not Found`: Token or scopes not accessible by user. + + tags: + - Tokens + operationId: token_scopes_list + produces: + - application/json + parameters: + - name: _id + in: path + required: true + type: string + description: The token's unique identifier. + responses: + '200': + description: Successfully retrieved tokens scopes. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "osf.full_write" + type: + type: string + example: scopes + attributes: + type: object + properties: + description: + type: string + example: "Full write access to OSF resources." + '404': + description: Token not found. From 68752cbd22c8234e574f020efda7b73d7f35b539 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Fri, 14 Mar 2025 11:26:16 -0400 Subject: [PATCH 05/21] add Application docs --- .../applications/application_detail.yaml | 104 +++++++++++++++++ .../applications/application_list.yaml | 110 ++++++++++++++++++ .../applications/application_reset.yaml | 34 ++++++ swagger-spec/swagger.yaml | 25 ++++ 4 files changed, 273 insertions(+) create mode 100644 swagger-spec/applications/application_detail.yaml create mode 100644 swagger-spec/applications/application_list.yaml create mode 100644 swagger-spec/applications/application_reset.yaml diff --git a/swagger-spec/applications/application_detail.yaml b/swagger-spec/applications/application_detail.yaml new file mode 100644 index 0000000..06bed92 --- /dev/null +++ b/swagger-spec/applications/application_detail.yaml @@ -0,0 +1,104 @@ +get: + summary: Retrieve Application Details + description: >- + Fetch detailed information for a specific OAuth2 application registered by the authenticated user. + + tags: + - Applications + operationId: application_detail + produces: + - application/json + parameters: + - name: client_id + in: path + required: true + type: string + description: The application's `client_id`. + responses: + '200': + description: Successfully retrieved application details. + examples: + application/json: + data: + id: "client_abc123" + type: "applications" + attributes: + name: "My App" + description: "An optional description" + home_url: "https://example.com" + callback_url: "https://example.com/oauth/callback" + owner: "user123" + date_created: "2024-03-14T10:00:00Z" + links: + html: "https://osf.io/settings/applications/client_abc123/" + reset: "https://api.osf.io/v2/applications/client_abc123/reset/" + +patch: + summary: Update Application + description: >- + Modify fields of an existing OAuth2 application. Fields such as `name`, `description`, `home_url`, or `callback_url` can be modified. + + To reset the client secret, set `"client_secret": ""`. + + tags: + - Applications + operationId: application_update + consumes: + - application/json + produces: + - application/json + parameters: + - name: client_id + in: path + required: true + type: string + - in: body + name: body + required: true + description: JSON:API payload with updated OAuth2 Application fields. + schema: + type: object + example: + application/json: + data: + type: "applications" + attributes: + name: "My Updated App" + description: "Updated description" + responses: + '200': + description: Application successfully updated. + examples: + application/json: + data: + id: "client_abc123" + type: "applications" + attributes: + name: "My Updated App" + description: "Updated description" + home_url: "https://example.com" + callback_url: "https://example.com/oauth/callback" + owner: "user123" + date_created: "2024-03-14T10:00:00Z" + links: + html: "https://osf.io/settings/applications/client_abc123/" + reset: "https://api.osf.io/v2/applications/client_abc123/reset/" + +delete: + summary: Deactivate Application + description: >- + Deactivates an OAuth2 application, hiding it from lists without deleting from the database. + + tags: + - Applications + operationId: application_deactivate + produces: + - application/json + parameters: + - name: client_id + in: path + required: true + type: string + responses: + '204': + description: Application successfully deactivated. diff --git a/swagger-spec/applications/application_list.yaml b/swagger-spec/applications/application_list.yaml new file mode 100644 index 0000000..9618577 --- /dev/null +++ b/swagger-spec/applications/application_list.yaml @@ -0,0 +1,110 @@ +get: + summary: List Registered Applications + description: >- + Retrieves a list of OAuth2 applications registered by the authenticated user. + + Applications allow external services to authenticate via OAuth2. + + #### Returns + + A JSON object containing an array of registered OAuth2 applications under the `data` key. + + tags: + - Applications + operationId: application_list + produces: + - application/json + responses: + '200': + description: Successfully retrieved list of applications. + examples: + application/json: + data: + - id: "abc123" + type: "applications" + attributes: + name: "My App" + description: "A sample application" + home_url: "https://example.com" + callback_url: "https://example.com/callback" + owner: "user123" + date_created: "2024-03-14T10:00:00Z" + links: + html: "https://osf.io/settings/applications/abc123/" + reset: "https://api.osf.io/v2/applications/abc123/reset/" + meta: + total: 1 + per_page: 10 + links: + self: "https://api.osf.io/v2/applications/" + +post: + summary: Create a New Application + description: >- + Registers a new OAuth2 application. + + The authenticated user becomes the owner of the application. + + tags: + - Applications + operationId: application_create + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + required: true + description: JSON:API payload representing the new OAuth2 Application. + schema: + type: object + properties: + data: + type: object + required: + - type + - attributes + properties: + type: + type: string + example: applications + attributes: + type: object + required: + - name + - home_url + - callback_url + properties: + name: + type: string + example: "My App" + description: + type: string + example: "An optional description" + home_url: + type: string + example: "https://example.com" + callback_url: + type: string + example: "https://example.com/oauth/callback" + responses: + '201': + description: OAuth2 Application successfully created. + examples: + application/json: + data: + id: "abc123" + type: applications + attributes: + name: "My App" + description: "An optional description" + home_url: "https://example.com" + callback_url: "https://example.com/oauth/callback" + client_id: "client_abc123" + client_secret: "secret_123" + owner: "user123" + date_created: "2024-03-14T10:00:00Z" + links: + html: "https://osf.io/settings/applications/client_abc123/" + reset: "https://api.osf.io/v2/applications/client_abc123/reset/" diff --git a/swagger-spec/applications/application_reset.yaml b/swagger-spec/applications/application_reset.yaml new file mode 100644 index 0000000..712ff8c --- /dev/null +++ b/swagger-spec/applications/application_reset.yaml @@ -0,0 +1,34 @@ +post: + summary: Reset Application Client Secret + description: >- + Resets the client secret for a specific OAuth2 application, revoking all associated tokens. + + **Deprecated in API v2.14+** + + tags: + - Applications + operationId: application_reset + produces: + - application/json + parameters: + - name: client_id + in: path + required: true + type: string + responses: + '201': + description: Client secret successfully reset. + examples: + application/json: + data: + id: "client_abc123" + type: "applications" + attributes: + client_secret: "new_secret_xyz789" + links: + html: "https://osf.io/settings/applications/client_abc123/" + reset: "https://api.osf.io/v2/applications/client_abc123/reset/" + '404': + description: Application not found or unauthorized. + '410': + description: Endpoint deprecated and removed in v2.15. diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index def7e93..ceb2031 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -34,6 +34,7 @@ x-tagGroups: - name: API Reference tags: - Addons + - Applications - Base - Citations - Comments @@ -875,6 +876,17 @@ tags: **Personal Access Tokens** allow users to authenticate API requests without credentials. Tokens support fine-grained permissions (scopes) to control API access levels. + - name: Applications + description: >- + **OAuth2 Applications** allow external services to securely authenticate and interact with OSF resources via OAuth2. + + Registered applications manage OAuth2 flows, client credentials, and access tokens. + + Operations include: + - Creating new OAuth2 applications + - Viewing and updating application details + - Deactivating or deleting applications + - Resetting client secrets (deprecated after v2.14) paths: @@ -1418,3 +1430,16 @@ paths: /tokens/{_id}/scopes/: $ref: 'tokens/token_scopes_list.yaml' + + ####################################### + # APPLICATIONS # + ####################################### + + /applications/: + $ref: 'applications/application_list.yaml' + + /applications/{client_id}/: + $ref: 'applications/application_detail.yaml' + + /applications/{client_id}/reset/: + $ref: 'applications/application_reset.yaml' From e7db48193422e6f70fec529b996ccee94315267c Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Fri, 14 Mar 2025 11:32:15 -0400 Subject: [PATCH 06/21] add Oauth scopes --- swagger-spec/scopes/scope_detail.yaml | 32 ++++++++++++++++++++ swagger-spec/scopes/scope_list.yaml | 43 +++++++++++++++++++++++++++ swagger-spec/swagger.yaml | 18 +++++++++++ 3 files changed, 93 insertions(+) create mode 100644 swagger-spec/scopes/scope_detail.yaml create mode 100644 swagger-spec/scopes/scope_list.yaml diff --git a/swagger-spec/scopes/scope_detail.yaml b/swagger-spec/scopes/scope_detail.yaml new file mode 100644 index 0000000..505cd77 --- /dev/null +++ b/swagger-spec/scopes/scope_detail.yaml @@ -0,0 +1,32 @@ +get: + summary: Retrieve OAuth Scope Detail + description: >- + Retrieve detailed information about a specific OAuth scope. + + Only publicly available scopes are accessible without special permissions. + + tags: + - OAuth Scopes + operationId: scope_detail + produces: + - application/json + parameters: + - name: scope_id + in: path + required: true + type: string + description: The unique identifier of the OAuth scope. + responses: + '200': + description: Successfully retrieved OAuth scope details. + examples: + application/json: + data: + id: "osf.nodes.read" + type: "scopes" + attributes: + description: "Read access to OSF nodes." + links: + self: "https://api.osf.io/v2/scopes/osf.nodes.read/" + '404': + description: OAuth scope not found or inaccessible. diff --git a/swagger-spec/scopes/scope_list.yaml b/swagger-spec/scopes/scope_list.yaml new file mode 100644 index 0000000..4f7db8c --- /dev/null +++ b/swagger-spec/scopes/scope_list.yaml @@ -0,0 +1,43 @@ +get: + summary: List OAuth Scopes + description: >- + Retrieve a list of publicly available OAuth scopes. + + Scopes define permissions granted to OAuth applications and personal access tokens. + + #### Filtering & Pagination + + Supports standard filtering and pagination via query parameters. + + #### Returns + + A JSON object containing an array of OAuth scopes under the `data` key. + + tags: + - OAuth Scopes + operationId: scope_list + produces: + - application/json + responses: + '200': + description: Successfully retrieved list of OAuth scopes. + examples: + application/json: + data: + - id: "osf.nodes.read" + type: "scopes" + attributes: + description: "Read access to OSF nodes." + links: + self: "https://api.osf.io/v2/scopes/osf.nodes.read/" + - id: "osf.nodes.write" + type: "scopes" + attributes: + description: "Write access to OSF nodes." + links: + self: "https://api.osf.io/v2/scopes/osf.nodes.write/" + links: + self: "https://api.osf.io/v2/scopes/" + meta: + total: 2 + per_page: 10 diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index ceb2031..f0c1deb 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -56,6 +56,7 @@ x-tagGroups: - Draft Registrations - Registrations - Regions + - OAuth Scopes - Taxonomies - Tokens - Users @@ -887,6 +888,13 @@ tags: - Viewing and updating application details - Deactivating or deleting applications - Resetting client secrets (deprecated after v2.14) + - name: OAuth Scopes + description: >- + OAuth scopes define specific permissions for OAuth applications and personal access tokens. + + Each scope indicates the permission level granted to perform actions via the OSF API, such as reading node data (`osf.nodes.read`) or modifying node data (`osf.nodes.write`). + + Scopes can be queried and managed through these endpoints to understand and control access levels associated with applications and tokens. paths: @@ -1443,3 +1451,13 @@ paths: /applications/{client_id}/reset/: $ref: 'applications/application_reset.yaml' + +####################################### +# OAUTH SCOPES # +####################################### + + /scopes/: + $ref: 'scopes/scope_list.yaml' + + /scopes/{scope_id}/: + $ref: 'scopes/scope_detail.yaml' From 54a65427f289b43a9b1a75307e2e934efd845626 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Tue, 18 Mar 2025 13:32:17 -0400 Subject: [PATCH 07/21] fix typo --- swagger-spec/swagger.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 1f5cf82..c7b8354 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -1488,5 +1488,5 @@ paths: /registration_subscriptions/{subscription_id}/: $ref: 'subscriptions/registration_subscription_detail.yaml' - /oollection_subscriptions/{subscription_id}/: + /collection_subscriptions/{subscription_id}/: $ref: 'subscriptions/collection_subscription_detail.yaml' From 254199e881913a69ec47b3e0f5ad1a6966be2c31 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Tue, 18 Mar 2025 14:35:59 -0400 Subject: [PATCH 08/21] Add Oauth scopes, Apps, tokens and Regions to docs --- .../applications/application_detail.yaml | 104 +++++++++++ .../applications/application_list.yaml | 110 ++++++++++++ .../applications/application_reset.yaml | 34 ++++ swagger-spec/region/region_detail.yaml | 66 +++++++ swagger-spec/region/region_list.yaml | 65 +++++++ swagger-spec/scopes/scope_detail.yaml | 32 ++++ swagger-spec/scopes/scope_list.yaml | 43 +++++ swagger-spec/swagger.yaml | 89 ++++++++- swagger-spec/tokens/detail.yaml | 1 - swagger-spec/tokens/list.yaml | 1 - swagger-spec/tokens/token_detail.yaml | 85 +++++++++ swagger-spec/tokens/token_list.yaml | 170 ++++++++++++++++++ swagger-spec/tokens/token_scopes_list.yaml | 51 ++++++ 13 files changed, 847 insertions(+), 4 deletions(-) create mode 100644 swagger-spec/applications/application_detail.yaml create mode 100644 swagger-spec/applications/application_list.yaml create mode 100644 swagger-spec/applications/application_reset.yaml create mode 100644 swagger-spec/region/region_detail.yaml create mode 100644 swagger-spec/region/region_list.yaml create mode 100644 swagger-spec/scopes/scope_detail.yaml create mode 100644 swagger-spec/scopes/scope_list.yaml delete mode 100644 swagger-spec/tokens/detail.yaml delete mode 100644 swagger-spec/tokens/list.yaml create mode 100644 swagger-spec/tokens/token_detail.yaml create mode 100644 swagger-spec/tokens/token_list.yaml create mode 100644 swagger-spec/tokens/token_scopes_list.yaml diff --git a/swagger-spec/applications/application_detail.yaml b/swagger-spec/applications/application_detail.yaml new file mode 100644 index 0000000..06bed92 --- /dev/null +++ b/swagger-spec/applications/application_detail.yaml @@ -0,0 +1,104 @@ +get: + summary: Retrieve Application Details + description: >- + Fetch detailed information for a specific OAuth2 application registered by the authenticated user. + + tags: + - Applications + operationId: application_detail + produces: + - application/json + parameters: + - name: client_id + in: path + required: true + type: string + description: The application's `client_id`. + responses: + '200': + description: Successfully retrieved application details. + examples: + application/json: + data: + id: "client_abc123" + type: "applications" + attributes: + name: "My App" + description: "An optional description" + home_url: "https://example.com" + callback_url: "https://example.com/oauth/callback" + owner: "user123" + date_created: "2024-03-14T10:00:00Z" + links: + html: "https://osf.io/settings/applications/client_abc123/" + reset: "https://api.osf.io/v2/applications/client_abc123/reset/" + +patch: + summary: Update Application + description: >- + Modify fields of an existing OAuth2 application. Fields such as `name`, `description`, `home_url`, or `callback_url` can be modified. + + To reset the client secret, set `"client_secret": ""`. + + tags: + - Applications + operationId: application_update + consumes: + - application/json + produces: + - application/json + parameters: + - name: client_id + in: path + required: true + type: string + - in: body + name: body + required: true + description: JSON:API payload with updated OAuth2 Application fields. + schema: + type: object + example: + application/json: + data: + type: "applications" + attributes: + name: "My Updated App" + description: "Updated description" + responses: + '200': + description: Application successfully updated. + examples: + application/json: + data: + id: "client_abc123" + type: "applications" + attributes: + name: "My Updated App" + description: "Updated description" + home_url: "https://example.com" + callback_url: "https://example.com/oauth/callback" + owner: "user123" + date_created: "2024-03-14T10:00:00Z" + links: + html: "https://osf.io/settings/applications/client_abc123/" + reset: "https://api.osf.io/v2/applications/client_abc123/reset/" + +delete: + summary: Deactivate Application + description: >- + Deactivates an OAuth2 application, hiding it from lists without deleting from the database. + + tags: + - Applications + operationId: application_deactivate + produces: + - application/json + parameters: + - name: client_id + in: path + required: true + type: string + responses: + '204': + description: Application successfully deactivated. diff --git a/swagger-spec/applications/application_list.yaml b/swagger-spec/applications/application_list.yaml new file mode 100644 index 0000000..9618577 --- /dev/null +++ b/swagger-spec/applications/application_list.yaml @@ -0,0 +1,110 @@ +get: + summary: List Registered Applications + description: >- + Retrieves a list of OAuth2 applications registered by the authenticated user. + + Applications allow external services to authenticate via OAuth2. + + #### Returns + + A JSON object containing an array of registered OAuth2 applications under the `data` key. + + tags: + - Applications + operationId: application_list + produces: + - application/json + responses: + '200': + description: Successfully retrieved list of applications. + examples: + application/json: + data: + - id: "abc123" + type: "applications" + attributes: + name: "My App" + description: "A sample application" + home_url: "https://example.com" + callback_url: "https://example.com/callback" + owner: "user123" + date_created: "2024-03-14T10:00:00Z" + links: + html: "https://osf.io/settings/applications/abc123/" + reset: "https://api.osf.io/v2/applications/abc123/reset/" + meta: + total: 1 + per_page: 10 + links: + self: "https://api.osf.io/v2/applications/" + +post: + summary: Create a New Application + description: >- + Registers a new OAuth2 application. + + The authenticated user becomes the owner of the application. + + tags: + - Applications + operationId: application_create + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + required: true + description: JSON:API payload representing the new OAuth2 Application. + schema: + type: object + properties: + data: + type: object + required: + - type + - attributes + properties: + type: + type: string + example: applications + attributes: + type: object + required: + - name + - home_url + - callback_url + properties: + name: + type: string + example: "My App" + description: + type: string + example: "An optional description" + home_url: + type: string + example: "https://example.com" + callback_url: + type: string + example: "https://example.com/oauth/callback" + responses: + '201': + description: OAuth2 Application successfully created. + examples: + application/json: + data: + id: "abc123" + type: applications + attributes: + name: "My App" + description: "An optional description" + home_url: "https://example.com" + callback_url: "https://example.com/oauth/callback" + client_id: "client_abc123" + client_secret: "secret_123" + owner: "user123" + date_created: "2024-03-14T10:00:00Z" + links: + html: "https://osf.io/settings/applications/client_abc123/" + reset: "https://api.osf.io/v2/applications/client_abc123/reset/" diff --git a/swagger-spec/applications/application_reset.yaml b/swagger-spec/applications/application_reset.yaml new file mode 100644 index 0000000..712ff8c --- /dev/null +++ b/swagger-spec/applications/application_reset.yaml @@ -0,0 +1,34 @@ +post: + summary: Reset Application Client Secret + description: >- + Resets the client secret for a specific OAuth2 application, revoking all associated tokens. + + **Deprecated in API v2.14+** + + tags: + - Applications + operationId: application_reset + produces: + - application/json + parameters: + - name: client_id + in: path + required: true + type: string + responses: + '201': + description: Client secret successfully reset. + examples: + application/json: + data: + id: "client_abc123" + type: "applications" + attributes: + client_secret: "new_secret_xyz789" + links: + html: "https://osf.io/settings/applications/client_abc123/" + reset: "https://api.osf.io/v2/applications/client_abc123/reset/" + '404': + description: Application not found or unauthorized. + '410': + description: Endpoint deprecated and removed in v2.15. diff --git a/swagger-spec/region/region_detail.yaml b/swagger-spec/region/region_detail.yaml new file mode 100644 index 0000000..984e6b1 --- /dev/null +++ b/swagger-spec/region/region_detail.yaml @@ -0,0 +1,66 @@ +# /regions/{region_id}/: + +get: + summary: Region Detail + description: >- + Retrieves detailed information for a specific storage region identified by `{region_id}`. + + A storage region defines the geographical or cloud-based location used by OSF Storage for storing files. + + ## Returns + A JSON:API-compliant response containing a single `region` entity under the `data` key. + + ## Errors + Returns an `errors` object if unsuccessful: + - `404 Not Found`: No region matches the provided `region_id`. + tags: + - Regions + operationId: region_detail + produces: + - application/json + parameters: + - name: region_id + in: path + description: The unique identifier for the region. + required: true + type: string + responses: + '200': + description: Successfully retrieved region details. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: us-east-1 + type: + type: string + example: regions + attributes: + type: object + properties: + name: + type: string + example: US East + links: + type: object + properties: + self: + type: string + example: 'https://api.osf.io/v2/regions/us-east-1/' + '404': + description: Region not found. + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + detail: + type: string + example: 'No region matching that region_id could be found.' diff --git a/swagger-spec/region/region_list.yaml b/swagger-spec/region/region_list.yaml new file mode 100644 index 0000000..ef18b71 --- /dev/null +++ b/swagger-spec/region/region_list.yaml @@ -0,0 +1,65 @@ +# /regions/: + +get: + summary: List Regions + description: >- + Retrieves a list of available storage regions within OSF. + + Regions define geographical or cloud storage locations for storing files uploaded through OSF Storage. + + ## Returns + A JSON:API-compliant response containing an array of regions under the `data` key, including region attributes such as `id` and `name`. + + Supports standard pagination and sorting by name. + + ## Errors + If unsuccessful, returns an `errors` object. Refer to the [Errors and Error Codes](#tag/Errors-and-Error-Codes) section for details. + tags: + - Regions + operationId: region_list + produces: + - application/json + responses: + '200': + description: Successfully retrieved the list of regions. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: us-east-1 + type: + type: string + example: regions + attributes: + type: object + properties: + name: + type: string + example: US East + links: + type: object + properties: + self: + type: string + example: 'https://api.osf.io/v2/regions/us-east-1/' + meta: + type: object + properties: + total: + type: integer + example: 1 + per_page: + type: integer + example: 10 + links: + type: object + properties: + self: + type: string + example: 'https://api.osf.io/v2/regions/' diff --git a/swagger-spec/scopes/scope_detail.yaml b/swagger-spec/scopes/scope_detail.yaml new file mode 100644 index 0000000..505cd77 --- /dev/null +++ b/swagger-spec/scopes/scope_detail.yaml @@ -0,0 +1,32 @@ +get: + summary: Retrieve OAuth Scope Detail + description: >- + Retrieve detailed information about a specific OAuth scope. + + Only publicly available scopes are accessible without special permissions. + + tags: + - OAuth Scopes + operationId: scope_detail + produces: + - application/json + parameters: + - name: scope_id + in: path + required: true + type: string + description: The unique identifier of the OAuth scope. + responses: + '200': + description: Successfully retrieved OAuth scope details. + examples: + application/json: + data: + id: "osf.nodes.read" + type: "scopes" + attributes: + description: "Read access to OSF nodes." + links: + self: "https://api.osf.io/v2/scopes/osf.nodes.read/" + '404': + description: OAuth scope not found or inaccessible. diff --git a/swagger-spec/scopes/scope_list.yaml b/swagger-spec/scopes/scope_list.yaml new file mode 100644 index 0000000..4f7db8c --- /dev/null +++ b/swagger-spec/scopes/scope_list.yaml @@ -0,0 +1,43 @@ +get: + summary: List OAuth Scopes + description: >- + Retrieve a list of publicly available OAuth scopes. + + Scopes define permissions granted to OAuth applications and personal access tokens. + + #### Filtering & Pagination + + Supports standard filtering and pagination via query parameters. + + #### Returns + + A JSON object containing an array of OAuth scopes under the `data` key. + + tags: + - OAuth Scopes + operationId: scope_list + produces: + - application/json + responses: + '200': + description: Successfully retrieved list of OAuth scopes. + examples: + application/json: + data: + - id: "osf.nodes.read" + type: "scopes" + attributes: + description: "Read access to OSF nodes." + links: + self: "https://api.osf.io/v2/scopes/osf.nodes.read/" + - id: "osf.nodes.write" + type: "scopes" + attributes: + description: "Write access to OSF nodes." + links: + self: "https://api.osf.io/v2/scopes/osf.nodes.write/" + links: + self: "https://api.osf.io/v2/scopes/" + meta: + total: 2 + per_page: 10 diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 20ea459..f0c1deb 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -34,6 +34,7 @@ x-tagGroups: - name: API Reference tags: - Addons + - Applications - Base - Citations - Comments @@ -54,7 +55,10 @@ x-tagGroups: - Preprint Providers - Draft Registrations - Registrations + - Regions + - OAuth Scopes - Taxonomies + - Tokens - Users - View Only Links tags: @@ -854,8 +858,43 @@ tags: adheres to the standards set for collection submissions. It aids in providing transparency and order to the process of managing collections and ensures that moderators and admins have the tools and information they need to effectively manage collection submissions. - - + - name: Regions + description: >- + Storage Regions are predefined geographical or cloud-storage areas where files are stored within OSF Storage. + + Each region provides isolation of data in compliance with geographic or regulatory requirements. Users can specify their preferred region for storing project files when using OSF Storage. + + **Attributes include:** + + - `id`: Unique identifier of the region (e.g., `us-east-1`). + - `name`: Human-readable name for the region (e.g., `US East`). + + **Endpoints include:** + - **List Regions:** Retrieve all available storage regions. + - **Region Detail:** Retrieve details about a specific storage region. + - name: Tokens + description: >- + **Personal Access Tokens** allow users to authenticate API requests without credentials. + + Tokens support fine-grained permissions (scopes) to control API access levels. + - name: Applications + description: >- + **OAuth2 Applications** allow external services to securely authenticate and interact with OSF resources via OAuth2. + + Registered applications manage OAuth2 flows, client credentials, and access tokens. + + Operations include: + - Creating new OAuth2 applications + - Viewing and updating application details + - Deactivating or deleting applications + - Resetting client secrets (deprecated after v2.14) + - name: OAuth Scopes + description: >- + OAuth scopes define specific permissions for OAuth applications and personal access tokens. + + Each scope indicates the permission level granted to perform actions via the OSF API, such as reading node data (`osf.nodes.read`) or modifying node data (`osf.nodes.write`). + + Scopes can be queried and managed through these endpoints to understand and control access levels associated with applications and tokens. paths: @@ -1376,3 +1415,49 @@ paths: /provider/collections/{collection_id}/moderators/{moderator_id}/: $ref: 'collection_provider/moderators_detail.yaml' + + ####################################### + # REGIONS # + ####################################### + + /regions/: + $ref: 'region/region_list.yaml' + + /regions/{region_id}/: + $ref: 'region/region_detail.yaml' + + ############################ + # TOKENS # + ############################ + + /tokens/: + $ref: 'tokens/token_list.yaml' + + /tokens/{_id}/: + $ref: 'tokens/token_detail.yaml' + + /tokens/{_id}/scopes/: + $ref: 'tokens/token_scopes_list.yaml' + + ####################################### + # APPLICATIONS # + ####################################### + + /applications/: + $ref: 'applications/application_list.yaml' + + /applications/{client_id}/: + $ref: 'applications/application_detail.yaml' + + /applications/{client_id}/reset/: + $ref: 'applications/application_reset.yaml' + +####################################### +# OAUTH SCOPES # +####################################### + + /scopes/: + $ref: 'scopes/scope_list.yaml' + + /scopes/{scope_id}/: + $ref: 'scopes/scope_detail.yaml' diff --git a/swagger-spec/tokens/detail.yaml b/swagger-spec/tokens/detail.yaml deleted file mode 100644 index 2735eae..0000000 --- a/swagger-spec/tokens/detail.yaml +++ /dev/null @@ -1 +0,0 @@ -# /tokens/{_id}/ diff --git a/swagger-spec/tokens/list.yaml b/swagger-spec/tokens/list.yaml deleted file mode 100644 index 7ffeb57..0000000 --- a/swagger-spec/tokens/list.yaml +++ /dev/null @@ -1 +0,0 @@ -# /tokens/ diff --git a/swagger-spec/tokens/token_detail.yaml b/swagger-spec/tokens/token_detail.yaml new file mode 100644 index 0000000..c9626d1 --- /dev/null +++ b/swagger-spec/tokens/token_detail.yaml @@ -0,0 +1,85 @@ +# /tokens/{_id}/: + +get: + summary: Personal Access Token Detail + description: >- + Retrieve details of a specific personal access token. + + #### Returns + A JSON:API-compliant response with the token's details. + + #### Errors + - `404 Not Found`: Token not found or not owned by the user. + + tags: + - Tokens + operationId: token_detail + produces: + - application/json + parameters: + - name: _id + in: path + required: true + type: string + description: The tokens's unique identifier. + responses: + '200': + description: Successful retrieval of tokens details. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: token123 + type: + type: string + example: tokens + attributes: + type: object + properties: + name: + type: string + example: "My API Token" + date_created: + type: string + format: date-time + example: "2024-03-14T15:00:00Z" + relationships: + type: object + properties: + scopes: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/tokens/token123/scopes/" + '404': + description: Token not found. + +delete: + summary: Deactivate Personal Access Token + description: >- + Deactivate (revoke) a personal access token. The token becomes inactive but is retained in the database. + + #### Errors + - `404 Not Found`: Token does not exist or is not accessible. + + tags: + - Tokens + operationId: token_deactivate + parameters: + - name: _id + in: path + required: true + type: string + description: The tokens's unique identifier. + responses: + '204': + description: Token successfully deactivated. + diff --git a/swagger-spec/tokens/token_list.yaml b/swagger-spec/tokens/token_list.yaml new file mode 100644 index 0000000..54d8219 --- /dev/null +++ b/swagger-spec/tokens/token_list.yaml @@ -0,0 +1,170 @@ +# /tokens/: + +get: + summary: List Personal Access Tokens + description: >- + Retrieve a list of active personal access tokens created by the authenticated user. + + Personal access tokens are used to authenticate requests to the OSF API without user credentials. + + #### Returns + A JSON:API-compliant response with an array of personal access token objects under the `data` key. + + #### Errors + Returns an `errors` object on failure. See [Errors and Error Codes](#tag/Errors-and-Error-Codes). + + tags: + - Tokens + operationId: token_list + produces: + - application/json + responses: + '200': + description: Successful retrieval of personal access tokens. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: token123 + type: + type: string + example: tokens + attributes: + type: object + properties: + name: + type: string + example: "My API Token" + date_created: + type: string + format: date-time + example: "2024-03-14T15:00:00Z" + relationships: + type: object + properties: + scopes: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/tokens/token123/scopes/" + meta: + type: object + properties: + total: + type: integer + example: 1 + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/tokens/" + +post: + summary: Create Personal Access Token + description: >- + Create a new personal access token for authenticating API requests. + + #### Request Body + A JSON:API-compliant request with token attributes (`name`) and `scopes` as relationships. + + #### Returns + A `201 Created` response with the newly created token details, including the token itself (`token_id`). + + **Note:** The token (`token_id`) is returned **only once** during creation. + + #### Errors + - `400 Bad Request`: Missing required fields or invalid scope. + - `403 Forbidden`: User lacks permission to create tokens. + + tags: + - Tokens + operationId: token_create + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: object + required: [type, attributes, relationships] + properties: + type: + type: string + example: tokens + attributes: + type: object + properties: + name: + type: string + example: "My API Token" + relationships: + type: object + properties: + scopes: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: scopes + id: + type: string + example: "osf.full_write" + + responses: + '201': + description: Token successfully created. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: token123 + type: + type: string + example: tokens + attributes: + type: object + properties: + name: + type: string + example: "My API Token" + token_id: + type: string + example: "abc123def456" + relationships: + type: object + properties: + scopes: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/tokens/token123/scopes/" diff --git a/swagger-spec/tokens/token_scopes_list.yaml b/swagger-spec/tokens/token_scopes_list.yaml new file mode 100644 index 0000000..238a112 --- /dev/null +++ b/swagger-spec/tokens/token_scopes_list.yaml @@ -0,0 +1,51 @@ +# /tokens/{_id}/scopes/: + +get: + summary: List Scopes of a Personal Access Token + description: >- + Retrieve the scopes associated with a specific personal access token. + + Scopes determine the level of access and operations permitted by the token. + + #### Returns + A JSON:API-compliant response containing an array of scopes. + + #### Errors + - `404 Not Found`: Token or scopes not accessible by user. + + tags: + - Tokens + operationId: token_scopes_list + produces: + - application/json + parameters: + - name: _id + in: path + required: true + type: string + description: The token's unique identifier. + responses: + '200': + description: Successfully retrieved tokens scopes. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "osf.full_write" + type: + type: string + example: scopes + attributes: + type: object + properties: + description: + type: string + example: "Full write access to OSF resources." + '404': + description: Token not found. From cf105b24abbd2a1cf1cd51f631682212fae2f22b Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Tue, 18 Mar 2025 15:15:12 -0400 Subject: [PATCH 09/21] Add miscellaneous and top-level API docs to complete documentation of Django V2 enpoints. --- swagger-spec/cedar_metadata/definition.yaml | 51 +++++ .../cedar_metadata/definition_create.yaml | 53 ++++++ swagger-spec/cedar_metadata/files_list.yaml | 39 ++++ swagger-spec/cedar_metadata/nodes_list.yaml | 39 ++++ .../custom_metadata/definition_file.yaml | 65 +++++++ .../custom_metadata/definition_nodes.yaml | 57 ++++++ swagger-spec/custom_metadata/files_list.yaml | 63 +++++++ swagger-spec/custom_metadata/nodes_list.yaml | 62 ++++++ .../bibliographic_contributor_list.yaml | 60 ++++++ .../relationships_institutions_list.yaml | 114 +++++++++++ .../relationships_subjects_list.yaml | 113 +++++++++++ swagger-spec/guids/detail.yaml | 118 ++++++++++++ .../institutions/relationships_nodes.yaml | 156 +++++++++++++++ .../relationships_registrations.yaml | 156 +++++++++++++++ swagger-spec/requests/actions_list.yaml | 96 ++++++++++ swagger-spec/requests/detail.yaml | 138 ++++++++++++++ .../requests/node_request_definition.yaml | 91 +++++++++ .../preprint_request_action_definition.yaml | 68 +++++++ swagger-spec/resources/definition.yaml | 83 ++++++++ swagger-spec/resources/detail.yaml | 111 +++++++++++ swagger-spec/resources/list.yaml | 155 +++++++++++++++ swagger-spec/subjects/children_list.yaml | 101 ++++++++++ swagger-spec/subjects/detail.yaml | 87 +++++++++ swagger-spec/subjects/list.yaml | 123 ++++++++++++ swagger-spec/swagger.yaml | 178 +++++++++++++++++- swagger-spec/wikis/content_detail.yaml | 0 swagger-spec/wikis/versions_content_list.yaml | 45 +++++ swagger-spec/wikis/versions_detail.yaml | 57 ++++++ swagger-spec/wikis/versions_list.yaml | 62 ++++++ 29 files changed, 2539 insertions(+), 2 deletions(-) create mode 100644 swagger-spec/cedar_metadata/definition.yaml create mode 100644 swagger-spec/cedar_metadata/definition_create.yaml create mode 100644 swagger-spec/cedar_metadata/files_list.yaml create mode 100644 swagger-spec/cedar_metadata/nodes_list.yaml create mode 100644 swagger-spec/custom_metadata/definition_file.yaml create mode 100644 swagger-spec/custom_metadata/definition_nodes.yaml create mode 100644 swagger-spec/custom_metadata/files_list.yaml create mode 100644 swagger-spec/custom_metadata/nodes_list.yaml create mode 100644 swagger-spec/draft_registrations/bibliographic_contributor_list.yaml create mode 100644 swagger-spec/draft_registrations/relationships_institutions_list.yaml create mode 100644 swagger-spec/draft_registrations/relationships_subjects_list.yaml create mode 100644 swagger-spec/guids/detail.yaml create mode 100644 swagger-spec/institutions/relationships_nodes.yaml create mode 100644 swagger-spec/institutions/relationships_registrations.yaml create mode 100644 swagger-spec/requests/actions_list.yaml create mode 100644 swagger-spec/requests/detail.yaml create mode 100644 swagger-spec/requests/node_request_definition.yaml create mode 100644 swagger-spec/requests/preprint_request_action_definition.yaml create mode 100644 swagger-spec/resources/definition.yaml create mode 100644 swagger-spec/resources/detail.yaml create mode 100644 swagger-spec/resources/list.yaml create mode 100644 swagger-spec/subjects/children_list.yaml create mode 100644 swagger-spec/subjects/detail.yaml create mode 100644 swagger-spec/subjects/list.yaml create mode 100644 swagger-spec/wikis/content_detail.yaml create mode 100644 swagger-spec/wikis/versions_content_list.yaml create mode 100644 swagger-spec/wikis/versions_detail.yaml create mode 100644 swagger-spec/wikis/versions_list.yaml diff --git a/swagger-spec/cedar_metadata/definition.yaml b/swagger-spec/cedar_metadata/definition.yaml new file mode 100644 index 0000000..bf56bd5 --- /dev/null +++ b/swagger-spec/cedar_metadata/definition.yaml @@ -0,0 +1,51 @@ +definitions: + CedarMetadataRecord: + type: object + required: + - id + - type + - attributes + - relationships + properties: + id: + type: string + example: record-abc123 + type: + type: string + example: cedar-metadata-records + attributes: + type: object + properties: + metadata: + type: object + description: The metadata object. + example: + title: Example Title + description: Example Description + is_published: + type: boolean + example: true + relationships: + type: object + properties: + template: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: template-abc123 + type: + type: string + example: cedar-metadata-templates + links: + type: object + properties: + self: + type: string + example: https://api.osf.io/v2/_/cedar_metadata_records/record-abc123/ + metadata_download: + type: string + example: https://api.osf.io/v2/_/cedar_metadata_records/record-abc123/metadata_download/ diff --git a/swagger-spec/cedar_metadata/definition_create.yaml b/swagger-spec/cedar_metadata/definition_create.yaml new file mode 100644 index 0000000..debbb23 --- /dev/null +++ b/swagger-spec/cedar_metadata/definition_create.yaml @@ -0,0 +1,53 @@ +definitions: + CedarMetadataRecordCreate: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - attributes + - relationships + properties: + type: + type: string + example: cedar-metadata-records + attributes: + type: object + required: + - metadata + - is_published + properties: + metadata: + type: object + description: Metadata fields defined by the CEDAR template. + example: + title: Example Title + description: Example Description + is_published: + type: boolean + example: false + relationships: + type: object + required: + - template + properties: + template: + type: object + description: The CEDAR template this record uses. + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + description: ID of the template. + example: 123abc + type: + type: string + example: cedar-metadata-templates diff --git a/swagger-spec/cedar_metadata/files_list.yaml b/swagger-spec/cedar_metadata/files_list.yaml new file mode 100644 index 0000000..f0e13c8 --- /dev/null +++ b/swagger-spec/cedar_metadata/files_list.yaml @@ -0,0 +1,39 @@ +post: + summary: Create a CEDAR metadata record for a file + description: > + Create a new CEDAR metadata record for the specified file. CEDAR metadata records follow + structured templates and can include rich metadata for data sharing and reuse. + operationId: createCedarMetadataRecordForFile + tags: + - CEDAR Metadata + consumes: + - application/vnd.api+json + produces: + - application/vnd.api+json + parameters: + - name: file_id + in: path + description: The unique identifier of the file. + required: true + type: string + - in: body + name: body + description: CEDAR metadata record object to be created. + required: true + schema: + $ref: './definition_create.yaml#/definitions/CedarMetadataRecordCreate' + responses: + '201': + description: Successfully created a new 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 create metadata for this file. + '404': + description: File not found. + security: + - osf_cookie: [] diff --git a/swagger-spec/cedar_metadata/nodes_list.yaml b/swagger-spec/cedar_metadata/nodes_list.yaml new file mode 100644 index 0000000..4dcb71c --- /dev/null +++ b/swagger-spec/cedar_metadata/nodes_list.yaml @@ -0,0 +1,39 @@ +post: + summary: Create a CEDAR metadata record for a node + description: > + Create a new CEDAR metadata record for the specified node. CEDAR metadata records are based + on predefined templates and can be associated with nodes or files. + operationId: createCedarMetadataRecordForNode + tags: + - CEDAR Metadata + consumes: + - application/vnd.api+json + produces: + - application/vnd.api+json + parameters: + - name: node_id + in: path + description: The unique identifier of the node. + required: true + type: string + - in: body + name: body + description: CEDAR metadata record object to be created. + required: true + schema: + $ref: './definition_create.yaml#/definitions/CedarMetadataRecordCreate' + responses: + '201': + description: Successfully created a new 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 create metadata for this node. + '404': + description: Node not found. + security: + - osf_cookie: [] diff --git a/swagger-spec/custom_metadata/definition_file.yaml b/swagger-spec/custom_metadata/definition_file.yaml new file mode 100644 index 0000000..cc5523a --- /dev/null +++ b/swagger-spec/custom_metadata/definition_file.yaml @@ -0,0 +1,65 @@ +type: object +required: + - data +properties: + data: + type: object + required: + - type + - attributes + properties: + type: + type: string + description: The resource type. + example: "custom-file-metadata-records" + attributes: + type: object + properties: + title: + type: string + description: The title of the file. + example: "My Dataset File" + description: + type: string + description: A description of the file. + example: "This file contains raw data collected from fieldwork." + language: + type: string + description: The language of the content. + example: "en" + resource_type_general: + type: string + description: The general type of the resource. + example: "Dataset" + funders: + type: array + description: Information about funding sources. + items: + type: object + required: + - funder_name + properties: + funder_name: + type: string + example: "National Science Foundation" + funder_identifier: + type: string + example: "123456" + funder_identifier_type: + type: string + enum: + - ISNI + - GRID + - Crossref Funder ID + - ROR + - Other + example: "ROR" + award_number: + type: string + example: "NSF-1234" + award_uri: + type: string + example: "https://nsf.gov/awardsearch/showAward?AWD_ID=1234" + award_title: + type: string + example: "Climate Change Research Grant" diff --git a/swagger-spec/custom_metadata/definition_nodes.yaml b/swagger-spec/custom_metadata/definition_nodes.yaml new file mode 100644 index 0000000..aac6aa6 --- /dev/null +++ b/swagger-spec/custom_metadata/definition_nodes.yaml @@ -0,0 +1,57 @@ +type: object +required: + - data +properties: + data: + type: object + required: + - type + - attributes + properties: + type: + type: string + description: The resource type. + example: "custom-item-metadata-records" + attributes: + type: object + properties: + language: + type: string + description: The language of the content. + example: "en" + resource_type_general: + type: string + description: The general type of the resource. + example: "Dataset" + funders: + type: array + description: Information about funding sources. + items: + type: object + required: + - funder_name + properties: + funder_name: + type: string + example: "National Science Foundation" + funder_identifier: + type: string + example: "123456" + funder_identifier_type: + type: string + enum: + - ISNI + - GRID + - Crossref Funder ID + - ROR + - Other + example: "ROR" + award_number: + type: string + example: "NSF-1234" + award_uri: + type: string + example: "https://nsf.gov/awardsearch/showAward?AWD_ID=1234" + award_title: + type: string + example: "Climate Change Research Grant" diff --git a/swagger-spec/custom_metadata/files_list.yaml b/swagger-spec/custom_metadata/files_list.yaml new file mode 100644 index 0000000..ade725d --- /dev/null +++ b/swagger-spec/custom_metadata/files_list.yaml @@ -0,0 +1,63 @@ +get: + summary: Retrieve custom file metadata for a file + description: > + Retrieve a custom file metadata record associated with a specific file by its GUID. + Custom file metadata includes fields such as title, description, language, and funding information. + operationId: getCustomFileMetadataRecord + tags: + - Custom Metadata + parameters: + - name: guid_id + in: path + description: The unique identifier (GUID) of the file. + required: true + type: string + responses: + '200': + description: Successfully retrieved custom file metadata record. + schema: + $ref: './schemas/custom_file_metadata_record.yaml' + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to access this metadata record. + '404': + description: Metadata record not found. + security: + - osf_cookie: [] + +patch: + summary: Update custom file metadata for a file + description: > + Update an existing custom file metadata record. Editable fields include title, description, + language, resource type, and funding information. + operationId: updateCustomFileMetadataRecord + tags: + - Custom Metadata + parameters: + - name: guid_id + in: path + description: The unique identifier (GUID) of the file. + required: true + type: string + - name: body + in: body + description: Custom file metadata record object. + required: true + schema: + $ref: 'definition_file.yaml' + responses: + '200': + description: Successfully updated custom file metadata record. + schema: + $ref: 'definition_file.yaml' + '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 modify this metadata record. + '404': + description: Metadata record not found. + security: + - osf_cookie: [] \ No newline at end of file diff --git a/swagger-spec/custom_metadata/nodes_list.yaml b/swagger-spec/custom_metadata/nodes_list.yaml new file mode 100644 index 0000000..8745380 --- /dev/null +++ b/swagger-spec/custom_metadata/nodes_list.yaml @@ -0,0 +1,62 @@ + get: + summary: Retrieve custom item metadata for a node or preprint + description: > + Retrieve a custom item metadata record associated with a node or preprint by its GUID. + Custom item metadata includes fields like language, resource type, and funding information. + operationId: getCustomItemMetadataRecord + tags: + - Custom Metadata + parameters: + - name: guid_id + in: path + description: The unique identifier (GUID) of the node or preprint. + required: true + type: string + responses: + '200': + description: Successfully retrieved custom item metadata record. + schema: + $ref: 'definition_nodes.yaml' + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to access this metadata record. + '404': + description: Metadata record not found. + security: + - osf_cookie: [] +patch: + summary: Update custom item metadata for a node or preprint + description: > + Update an existing custom item metadata record for a node or preprint. Editable fields + include language, resource type, and funding information. + operationId: updateCustomItemMetadataRecord + tags: + - Custom Metadata + parameters: + - name: guid_id + in: path + description: The unique identifier (GUID) of the node or preprint. + required: true + type: string + - name: body + in: body + description: Custom item metadata record object. + required: true + schema: + $ref: 'definition_nodes.yaml' + responses: + '200': + description: Successfully updated custom item metadata record. + schema: + $ref: 'definition_nodes.yaml' + '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 modify this metadata record. + '404': + description: Metadata record not found. + security: + - osf_cookie: [] \ No newline at end of file diff --git a/swagger-spec/draft_registrations/bibliographic_contributor_list.yaml b/swagger-spec/draft_registrations/bibliographic_contributor_list.yaml new file mode 100644 index 0000000..3986927 --- /dev/null +++ b/swagger-spec/draft_registrations/bibliographic_contributor_list.yaml @@ -0,0 +1,60 @@ +get: + summary: List bibliographic contributors on a draft registration + description: Retrieve a list of contributors marked as bibliographic (visible) for a draft registration. + tags: + - Draft Registrations + - Contributors + operationId: draft_registration_bibliographic_contributors_list + parameters: + - name: draft_id + in: path + required: true + type: string + description: Draft registration ID. + responses: + '200': + description: Bibliographic contributors retrieved successfully. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: [id, type, attributes] + properties: + id: + type: string + description: Contributor ID + type: + type: string + example: contributors + attributes: + type: object + properties: + full_name: + type: string + bibliographic: + type: boolean + description: Indicates if the contributor is visible. + email: + type: string + description: Email of the contributor. + example: + data: + - id: user123 + type: contributors + attributes: + full_name: Alice Smith + bibliographic: true + email: alice@example.com + - id: user456 + type: contributors + attributes: + full_name: Bob Jones + bibliographic: true + email: bob@example.com + '403': + description: Forbidden. + '404': + description: Draft registration not found. diff --git a/swagger-spec/draft_registrations/relationships_institutions_list.yaml b/swagger-spec/draft_registrations/relationships_institutions_list.yaml new file mode 100644 index 0000000..a963680 --- /dev/null +++ b/swagger-spec/draft_registrations/relationships_institutions_list.yaml @@ -0,0 +1,114 @@ +get: + summary: Retrieve affiliated institutions for a draft registration + description: Get all institutions affiliated with the draft registration. + tags: + - Draft Registrations + - Institutions + operationId: draft_registration_institutions_relationship_retrieve + parameters: + - name: draft_id + in: path + required: true + type: string + description: Draft registration ID. + responses: + '200': + description: Institutions retrieved successfully. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: [type, id] + properties: + type: + type: string + example: institutions + id: + type: string + example: + data: + - type: institutions + id: inst123 + - type: institutions + id: inst456 + '403': + description: Forbidden. + '404': + description: Draft registration not found. + +post: + summary: Add affiliated institutions to a draft registration + description: Add institutions to the draft registration. + tags: + - Draft Registrations + - Institutions + operationId: draft_registration_institutions_relationship_add + parameters: + - name: draft_id + in: path + required: true + type: string + - in: body + name: body + schema: + type: object + properties: + data: + type: array + items: + type: object + required: [type, id] + properties: + type: + type: string + example: institutions + id: + type: string + responses: + '204': + description: Institutions added successfully. + '400': + description: User is not affiliated with the institution. + '403': + description: Forbidden. + '404': + description: Draft registration not found. + +delete: + summary: Remove affiliated institutions from a draft registration + description: Remove institutions from the draft registration. + tags: + - Draft Registrations + - Institutions + operationId: draft_registration_institutions_relationship_delete + parameters: + - name: draft_id + in: path + required: true + type: string + - in: body + name: body + schema: + type: object + properties: + data: + type: array + items: + type: object + required: [type, id] + properties: + type: + type: string + example: institutions + id: + type: string + responses: + '204': + description: Institutions removed successfully. + '403': + description: Forbidden. + '404': + description: Draft registration not found. diff --git a/swagger-spec/draft_registrations/relationships_subjects_list.yaml b/swagger-spec/draft_registrations/relationships_subjects_list.yaml new file mode 100644 index 0000000..8865a8c --- /dev/null +++ b/swagger-spec/draft_registrations/relationships_subjects_list.yaml @@ -0,0 +1,113 @@ + +get: + summary: Retrieve subjects relationship for a draft registration + description: Get the subjects associated with a draft registration. + tags: + - Draft Registrations + - Subjects + operationId: draft_registration_subjects_relationship_retrieve + parameters: + - name: draft_id + in: path + required: true + type: string + description: The unique identifier of the draft registration. + responses: + '200': + description: Subjects retrieved successfully. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: subjects + id: + type: string + description: Subject ID + example: + data: + - type: subjects + id: abc123 + - type: subjects + id: def456 + '403': + description: Forbidden. You don't have permission to view these subjects. + '404': + description: Draft registration not found. + +post: + summary: Add subjects to a draft registration + description: Add subjects by ID to the draft registration. + tags: + - Draft Registrations + - Subjects + operationId: draft_registration_subjects_relationship_add + parameters: + - name: draft_id + in: path + required: true + type: string + - in: body + name: body + schema: + type: object + properties: + data: + type: array + items: + type: object + required: [type, id] + properties: + type: + type: string + example: subjects + id: + type: string + responses: + '204': + description: Subjects added successfully. + '403': + description: Forbidden. You don't have permission to modify subjects. + '404': + description: Draft registration not found. + +delete: + summary: Remove subjects from a draft registration + description: Remove subjects from the draft registration by ID. + tags: + - Draft Registrations + - Subjects + operationId: draft_registration_subjects_relationship_delete + parameters: + - name: draft_id + in: path + required: true + type: string + - in: body + name: body + schema: + type: object + properties: + data: + type: array + items: + type: object + required: [type, id] + properties: + type: + type: string + example: subjects + id: + type: string + responses: + '204': + description: Subjects removed successfully. + '403': + description: Forbidden. You don't have permission to modify subjects. + '404': + description: Draft registration not found. diff --git a/swagger-spec/guids/detail.yaml b/swagger-spec/guids/detail.yaml new file mode 100644 index 0000000..8131727 --- /dev/null +++ b/swagger-spec/guids/detail.yaml @@ -0,0 +1,118 @@ +get: + summary: Retrieve a GUID resource or redirect to its referent resource + description: | + Retrieve a GUID object or be redirected to the most appropriate resource. + + By default, this endpoint will redirect (`302 Found`) to the resource URL associated with the GUID. + If `?resolve=false` is passed as a query parameter, the request returns the GUID resource itself instead of redirecting. + + This endpoint is helpful for resolving GUIDs that may refer to various OSF objects, including: + - Nodes + - Registrations + - Files + - Collections + - Preprints + - Users + + ### Redirect Behavior + - If the GUID is valid and points to a resource with an API endpoint, you will be redirected to that resource. + - If the GUID is valid but refers to an object with no endpoint (e.g., a wiki page), you will get a `501 Not Implemented`. + - If the GUID does not exist or has been deleted, a `404 Not Found` or `410 Gone` response is returned. + + ### JSON Response Behavior + If `resolve=false` is provided as a query parameter, a `200 OK` response returns the GUID resource and relationships to its referent and custom metadata records. + + ### Permissions + - Public GUIDs are available to unauthenticated users. + - Private GUIDs require appropriate read permissions. + + operationId: retrieveGuid + tags: + - GUIDs + parameters: + - name: guid_id + in: path + required: true + type: string + description: | + The unique identifier for the GUID. + This can refer to nodes, registrations, files, collections, preprints, or users. + - name: resolve + in: query + required: false + type: boolean + description: | + If true (default), redirects to the referent resource. + If false, returns a representation of the GUID resource itself. + responses: + '200': + description: Successfully retrieved the GUID resource. + schema: + type: object + properties: + data: + type: object + required: + - id + - type + - attributes + - relationships + - links + properties: + id: + type: string + example: abc123 + type: + type: string + example: guids + attributes: + type: object + properties: {} + relationships: + type: object + properties: + referent: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: https://api.osf.io/v2/nodes/abc123/ + meta: + type: object + properties: + type: + type: string + example: nodes + custom_metadata: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: https://api.osf.io/v2/custom_file_metadata_records/abc123/ + links: + type: object + properties: + self: + type: string + example: https://api.osf.io/v2/guids/abc123/ + html: + type: string + example: https://osf.io/abc123/ + '302': + description: Redirect to the referent resource. + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view this GUID. + '404': + description: The GUID does not exist. + '410': + description: The GUID once existed but has since been deleted. + produces: + - application/vnd.api+json diff --git a/swagger-spec/institutions/relationships_nodes.yaml b/swagger-spec/institutions/relationships_nodes.yaml new file mode 100644 index 0000000..248c9a6 --- /dev/null +++ b/swagger-spec/institutions/relationships_nodes.yaml @@ -0,0 +1,156 @@ +get: + summary: List nodes affiliated with an institution (relationship data) + description: | + Retrieve relationship data for nodes affiliated with the given institution. + + ### Permissions + - Public nodes: Anyone can view the affiliation. + - Private nodes: Only contributors can view affiliation. + - Requires read access to the institution and nodes. + + tags: + - Institutions + operationId: listInstitutionNodeRelationships + parameters: + - name: institution_id + in: path + required: true + type: string + description: The unique identifier of the institution. + responses: + '200': + description: Successfully retrieved node relationships. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: nodes + id: + type: string + example: abcd1 + links: + type: object + properties: + self: + type: string + example: /v2/institutions/{institution_id}/relationships/nodes/ + related: + type: string + example: /v2/institutions/{institution_id}/nodes/ + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view this institution's nodes. + '404': + description: Institution not found. + security: + - osf_cookie: [] + +post: + summary: Add node relationships to an institution + description: | + Add nodes to an institution's affiliated nodes relationship. + + ### Permissions + - Requires write access on each node being added. + - User must be affiliated with the institution. + + tags: + - Institutions + operationId: addInstitutionNodeRelationships + consumes: + - application/vnd.api+json + parameters: + - name: institution_id + in: path + required: true + type: string + description: The unique identifier of the institution. + - in: body + name: body + required: true + description: List of node relationships to add. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: nodes + id: + type: string + example: abcd1 + responses: + '201': + description: Nodes successfully affiliated with institution. + '204': + description: No changes made (nodes already affiliated). + '400': + description: Invalid request payload. + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to affiliate these nodes. + '404': + description: Institution not found. + security: + - osf_cookie: [] + +delete: + summary: Remove node relationships from an institution + description: | + Remove nodes from an institution's affiliated nodes relationship. + + ### Permissions + - Requires write access on each node being removed. + + tags: + - Institutions + operationId: removeInstitutionNodeRelationships + consumes: + - application/vnd.api+json + parameters: + - name: institution_id + in: path + required: true + type: string + description: The unique identifier of the institution. + - in: body + name: body + required: true + description: List of node relationships to remove. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: nodes + id: + type: string + example: abcd1 + responses: + '204': + description: Nodes successfully removed from affiliation. + '400': + description: Invalid request payload. + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to modify these nodes. + '404': + description: Institution not found. \ No newline at end of file diff --git a/swagger-spec/institutions/relationships_registrations.yaml b/swagger-spec/institutions/relationships_registrations.yaml new file mode 100644 index 0000000..2dc1872 --- /dev/null +++ b/swagger-spec/institutions/relationships_registrations.yaml @@ -0,0 +1,156 @@ +get: + summary: List registrations affiliated with an institution (relationship data) + description: | + Retrieve relationship data for registrations affiliated with the given institution. + + ### Permissions + - Public registrations: Anyone can view the affiliation. + - Private registrations: Only contributors can view affiliation. + - Requires read access to the institution and registrations. + + tags: + - Institutions + operationId: listInstitutionRegistrationRelationships + parameters: + - name: institution_id + in: path + required: true + type: string + description: The unique identifier of the institution. + responses: + '200': + description: Successfully retrieved registration relationships. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: registrations + id: + type: string + example: reg123 + links: + type: object + properties: + self: + type: string + example: /v2/institutions/{institution_id}/relationships/registrations/ + related: + type: string + example: /v2/institutions/{institution_id}/registrations/ + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view this institution's registrations. + '404': + description: Institution not found. + security: + - osf_cookie: [] + +post: + summary: Add registration relationships to an institution + description: | + Add registrations to an institution's affiliated registrations relationship. + + ### Permissions + - Requires write access on each registration being added. + - User must be affiliated with the institution. + + tags: + - Institutions + operationId: addInstitutionRegistrationRelationships + consumes: + - application/vnd.api+json + parameters: + - name: institution_id + in: path + required: true + type: string + description: The unique identifier of the institution. + - in: body + name: body + required: true + description: List of registration relationships to add. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: registrations + id: + type: string + example: reg123 + responses: + '201': + description: Registrations successfully affiliated with institution. + '204': + description: No changes made (registrations already affiliated). + '400': + description: Invalid request payload. + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to affiliate these registrations. + '404': + description: Institution not found. + security: + - osf_cookie: [] + +delete: + summary: Remove registration relationships from an institution + description: | + Remove registrations from an institution's affiliated registrations relationship. + + ### Permissions + - Requires write access on each registration being removed. + + tags: + - Institutions + operationId: removeInstitutionRegistrationRelationships + consumes: + - application/vnd.api+json + parameters: + - name: institution_id + in: path + required: true + type: string + description: The unique identifier of the institution. + - in: body + name: body + required: true + description: List of registration relationships to remove. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: registrations + id: + type: string + example: reg123 + responses: + '204': + description: Registrations successfully removed from affiliation. + '400': + description: Invalid request payload. + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to modify these registrations. + '404': + description: Institution not found. \ No newline at end of file diff --git a/swagger-spec/requests/actions_list.yaml b/swagger-spec/requests/actions_list.yaml new file mode 100644 index 0000000..a4ab256 --- /dev/null +++ b/swagger-spec/requests/actions_list.yaml @@ -0,0 +1,96 @@ +get: + summary: List actions associated with a request + description: > + Retrieve a list of actions performed on a specific request. + + Currently, actions are supported for `preprint-request` resources, typically related to withdrawal requests. + Actions track the workflow of the request, including submission, approvals, rejections, and comments. + + ### Permissions: + - Request creators can view actions on their requests. + - Preprint moderators can view actions for withdrawal requests. + - Preprint administrators can view actions on requests for preprints they manage. + tags: + - Requests + operationId: list_request_actions + parameters: + - name: request_id + in: path + required: true + type: string + description: The unique identifier for the request. + - name: filter + in: query + required: false + type: string + description: | + Filter actions by attributes. + + Supported filters: + - `machine_state`: Filter by current state (e.g., `pending`, `accepted`, `rejected`) + + Example: + - filter[machine_state]=pending + responses: + '200': + description: Successfully retrieved actions for the request. + schema: + type: object + properties: + data: + type: array + description: List of actions related to the request. + items: + $ref: './preprint_request_action_definition.yaml' + links: + type: object + description: Pagination links. + properties: + self: + type: string + example: /v2/requests/{request_id}/actions/?page=1 + next: + type: string + example: /v2/requests/{request_id}/actions/?page=2 + prev: + type: string + example: null + examples: + application/json: + data: + - id: "action123" + type: "preprint-request-actions" + attributes: + trigger: "accept" + comment: "Withdrawal approved." + from_state: "pending" + to_state: "accepted" + created: "2024-06-01T12:00:00Z" + relationships: + creator: + data: + id: "user456" + type: "users" + - id: "action456" + type: "preprint-request-actions" + attributes: + trigger: "submit" + comment: "Request submitted." + from_state: "initial" + to_state: "pending" + created: "2024-05-30T08:15:00Z" + relationships: + creator: + data: + id: "user456" + type: "users" + links: + self: /v2/requests/abc123/actions/?page=1 + next: null + prev: null + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view actions on this request. + '404': + description: Request not found or no actions are available for the given request. \ No newline at end of file diff --git a/swagger-spec/requests/detail.yaml b/swagger-spec/requests/detail.yaml new file mode 100644 index 0000000..89b2ef0 --- /dev/null +++ b/swagger-spec/requests/detail.yaml @@ -0,0 +1,138 @@ +get: + summary: Retrieve details for a specific request + description: > + Retrieve a specific request by ID. Requests can be associated with either a node or a preprint. + Depending on the type, this will return a `node-request` or a `preprint-request` resource. + + A request is a formal submission for actions like access to private content, withdrawal of a preprint, + or institutional affiliation. This endpoint returns details about the request's status, creator, type, and comments. + + Permissions: + - Node requests: Viewable by the node's administrators and the request creator. + - Preprint requests: Viewable by preprint admins, moderators (for moderated providers), and the request creator. + tags: + - Requests + operationId: retrieve_request + parameters: + - name: request_id + in: path + required: true + type: string + description: The unique identifier for the request (either NodeRequest or PreprintRequest). + responses: + '200': + description: Successfully retrieved request details. + schema: + type: object + description: > + Returns either a node-request or a preprint-request resource, following JSON:API format. + required: + - data + properties: + data: + type: object + required: + - id + - type + - attributes + - relationships + properties: + id: + type: string + description: Unique identifier for the request. + example: "abc123" + type: + type: string + description: Resource type. Will be `node-requests` or `preprint-requests`. + enum: [node-requests, preprint-requests] + attributes: + type: object + properties: + request_type: + type: string + description: > + Type of request. Examples: `access`, `withdrawal`, or `institutional_request`. + example: "access" + machine_state: + type: string + description: > + Current workflow state of the request. Examples: `pending`, `accepted`, `rejected`. + example: "pending" + comment: + type: string + description: Comment provided with the request. + example: "Please grant me access." + created: + type: string + format: date-time + description: ISO 8601 timestamp of when the request was created. + example: "2024-06-01T12:00:00Z" + modified: + type: string + format: date-time + description: ISO 8601 timestamp of the last modification to the request. + example: "2024-06-02T15:30:00Z" + date_last_transitioned: + type: string + format: date-time + description: > + ISO 8601 timestamp of when the request last transitioned to a new workflow state. + example: "2024-06-02T15:30:00Z" + relationships: + type: object + properties: + creator: + type: object + description: The user who created the request. + properties: + data: + type: object + properties: + id: + type: string + example: "user123" + type: + type: string + example: "users" + target: + type: object + description: > + The node or preprint this request is associated with. + properties: + data: + type: object + properties: + id: + type: string + example: "project456" + type: + type: string + example: "nodes" # or "preprints" + actions: + type: object + description: > + Related actions for the request (only for preprint-requests). + properties: + links: + type: object + properties: + related: + type: string + example: "/v2/requests/abc123/actions/" + links: + type: object + properties: + self: + type: string + example: "/v2/requests/abc123/" + target: + type: string + example: "/v2/nodes/project456/" + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view this request. + '404': + description: Request not found. + security: + - osf_cookie: [] diff --git a/swagger-spec/requests/node_request_definition.yaml b/swagger-spec/requests/node_request_definition.yaml new file mode 100644 index 0000000..3087e9f --- /dev/null +++ b/swagger-spec/requests/node_request_definition.yaml @@ -0,0 +1,91 @@ +type: object +required: + - id + - type + - attributes + - relationships +properties: + id: + type: string + description: The unique identifier for the node request. + example: "rqst12345" + type: + type: string + example: "node-requests" + attributes: + type: object + properties: + request_type: + type: string + description: > + The type of request, such as 'access' or 'institutional_request'. + enum: + - access + - institutional_request + example: "access" + machine_state: + type: string + description: > + The current state of the request in its workflow. + enum: + - initial + - pending + - accepted + - rejected + example: "pending" + comment: + type: string + description: > + Optional comment provided by the request creator. + example: "Requesting read access to this project." + requested_permissions: + type: string + description: > + Permissions level being requested. Only applies to access and institutional requests. + enum: + - read + - write + - admin + example: "read" + date_created: + type: string + format: date-time + description: Date and time the request was created. + date_modified: + type: string + format: date-time + description: Date and time the request was last modified. + date_last_transitioned: + type: string + format: date-time + description: > + The date and time when the request last changed its machine state. + relationships: + type: object + properties: + creator: + type: object + description: The user who created the request. + properties: + data: + type: object + properties: + id: + type: string + example: "user123" + type: + type: string + example: "users" + target: + type: object + description: The node that this request is targeting. + properties: + data: + type: object + properties: + id: + type: string + example: "abcde" + type: + type: string + example: "nodes" diff --git a/swagger-spec/requests/preprint_request_action_definition.yaml b/swagger-spec/requests/preprint_request_action_definition.yaml new file mode 100644 index 0000000..dac9e96 --- /dev/null +++ b/swagger-spec/requests/preprint_request_action_definition.yaml @@ -0,0 +1,68 @@ +type: object +required: + - id + - type + - attributes + - relationships +properties: + id: + type: string + description: The unique identifier for the preprint request action. + example: "actn54321" + type: + type: string + example: "preprint-request-actions" + attributes: + type: object + properties: + trigger: + type: string + description: The event that caused this action. + enum: + - submit + - accept + - reject + - edit_comment + example: "accept" + comment: + type: string + description: Optional comment made during the action. + example: "This withdrawal request has been approved." + auto: + type: boolean + description: > + Whether the action was triggered automatically by the system rather than manually by a user. + example: false + date_created: + type: string + format: date-time + description: Date and time the action was created. + relationships: + type: object + properties: + creator: + type: object + description: The user who performed this action. + properties: + data: + type: object + properties: + id: + type: string + example: "user789" + type: + type: string + example: "users" + target: + type: object + description: The preprint request this action is associated with. + properties: + data: + type: object + properties: + id: + type: string + example: "prrqst67890" + type: + type: string + example: "preprint-requests" diff --git a/swagger-spec/resources/definition.yaml b/swagger-spec/resources/definition.yaml new file mode 100644 index 0000000..a70f908 --- /dev/null +++ b/swagger-spec/resources/definition.yaml @@ -0,0 +1,83 @@ + description: A resource associated with a registration, such as datasets, materials, code, or papers. + type: object + required: + - data + properties: + data: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + example: "abc123" + description: Unique identifier of the resource. + type: + type: string + example: "resources" + description: The type of the resource object. + attributes: + type: object + properties: + date_created: + type: string + format: date-time + example: "2024-01-01T00:00:00Z" + description: The date the resource was created. + date_modified: + type: string + format: date-time + example: "2024-01-02T00:00:00Z" + description: The date the resource was last modified. + description: + type: string + example: "Dataset resource for analysis of trial results" + description: A brief description of the resource. + resource_type: + type: string + description: | + The type of the resource. Acceptable values include: + - data + - analytic_code + - materials + - papers + - supplements + example: "data" + finalized: + type: boolean + description: Indicates whether the resource has been finalized. + example: true + pid: + type: string + description: Persistent Identifier (PID) assigned to the resource. + example: "10.1234/osf.io/abcde" + relationships: + type: object + description: Relationships for the resource. + properties: + registration: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + example: "reg123" + description: The unique identifier of the registration the resource is linked to. + type: + type: string + example: "registrations" + description: Type for the registration relationship. + links: + type: object + properties: + self: + type: string + description: The canonical API endpoint for this resource. + example: "https://api.osf.io/v2/resources/abc123/" \ No newline at end of file diff --git a/swagger-spec/resources/detail.yaml b/swagger-spec/resources/detail.yaml new file mode 100644 index 0000000..31110c1 --- /dev/null +++ b/swagger-spec/resources/detail.yaml @@ -0,0 +1,111 @@ +get: + summary: Retrieve a resource + description: | + Retrieve details for a specific resource. + tags: + - Resources + operationId: getResource + parameters: + - name: resource_id + in: path + required: true + type: string + description: The unique identifier of the resource. + responses: + '200': + description: Successful retrieval of resource + schema: + $ref: 'definition.yaml' + '404': + description: Resource not found. + '401': + description: Authentication required. + '403': + description: Permission denied. + +patch: + summary: Update a resource + description: | + Update details for a specific resource. + tags: + - Resources + operationId: updateResource + parameters: + - name: resource_id + in: path + required: true + type: string + description: The unique identifier of the resource. + - name: body + in: body + description: Resource object to update + required: true + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + example: "abc123" + type: + type: string + example: "resources" + attributes: + type: object + properties: + description: + type: string + example: "Updated resource description" + resource_type: + type: string + example: "materials" + finalized: + type: boolean + example: true + pid: + type: string + example: "10.5678/resource.9012" + responses: + '200': + description: Successfully updated the resource + schema: + $ref: 'definition.yaml' + '400': + description: Validation error or invalid data. + '404': + description: Resource not found. + '401': + description: Authentication required. + '403': + description: Permission denied. + +delete: + summary: Delete a resource + description: | + Delete a specific resource. + tags: + - Resources + operationId: deleteResource + parameters: + - name: resource_id + in: path + required: true + type: string + description: The unique identifier of the resource. + responses: + '204': + description: Successfully deleted the resource + '404': + description: Resource not found. + '401': + description: Authentication required. + '403': + description: Permission denied. \ No newline at end of file diff --git a/swagger-spec/resources/list.yaml b/swagger-spec/resources/list.yaml new file mode 100644 index 0000000..d446d56 --- /dev/null +++ b/swagger-spec/resources/list.yaml @@ -0,0 +1,155 @@ + get: + summary: List resources + description: | + Retrieve a list of resources associated with registrations. + tags: + - Resources + operationId: listResources + responses: + '200': + description: Successful retrieval of resource list + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + - relationships + properties: + id: + type: string + example: "abc123" + type: + type: string + example: "resources" + attributes: + type: object + properties: + date_created: + type: string + format: date-time + example: "2024-01-01T00:00:00Z" + date_modified: + type: string + format: date-time + example: "2024-01-02T00:00:00Z" + description: + type: string + example: "Dataset resource" + resource_type: + type: string + example: "data" + finalized: + type: boolean + example: true + pid: + type: string + example: "10.1234/resource.5678" + relationships: + type: object + properties: + registration: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "reg123" + type: + type: string + example: "registrations" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/resources/abc123/" + meta: + type: object + properties: + total: + type: integer + example: 1 + per_page: + type: integer + example: 10 + page: + type: integer + example: 1 + '401': + description: Authentication required. + '403': + description: Permission denied. + + post: + summary: Create a new resource + description: | + Create a new resource associated with a registration. + tags: + - Resources + operationId: createResource + parameters: + - name: body + in: body + description: Resource object to create + required: true + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - attributes + - relationships + properties: + type: + type: string + example: "resources" + attributes: + type: object + properties: + description: + type: string + example: "Dataset resource" + resource_type: + type: string + example: "data" + relationships: + type: object + properties: + registration: + type: object + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + example: "registrations" + id: + type: string + example: "reg123" + responses: + '201': + description: Successfully created a new resource + schema: + $ref: 'definition.yaml' + '400': + description: Validation error or invalid data. + '401': + description: Authentication required. + '403': + description: Permission denied. \ No newline at end of file diff --git a/swagger-spec/subjects/children_list.yaml b/swagger-spec/subjects/children_list.yaml new file mode 100644 index 0000000..ba43b4e --- /dev/null +++ b/swagger-spec/subjects/children_list.yaml @@ -0,0 +1,101 @@ +get: + summary: List child subjects for a given subject + description: | + Retrieve all immediate child subjects for the given taxonomy subject. + Subjects are categorized hierarchically. + operationId: listSubjectChildren + tags: + - Subjects + parameters: + - name: subject_id + in: path + description: The unique identifier of the parent subject. + required: true + type: string + responses: + '200': + description: Successful retrieval of child subjects. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + example: "child123" + type: + type: string + example: "subjects" + attributes: + type: object + properties: + text: + type: string + example: "Sub-discipline Example" + taxonomy_name: + type: string + example: "OSF" + relationships: + type: object + properties: + parent: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + example: "abc123" + type: + type: string + example: "subjects" + children: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/subjects/child123/children/" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/subjects/{subject_id}/children/" + next: + type: string + example: "https://api.osf.io/v2/subjects/{subject_id}/children/?page=2" + prev: + type: string + example: "https://api.osf.io/v2/subjects/{subject_id}/children/?page=1" + meta: + type: object + properties: + total: + type: integer + example: 20 + per_page: + type: integer + example: 10 + page: + type: integer + example: 1 + '404': + description: Parent subject not found. + security: + - osf_cookie: [] + produces: + - application/vnd.api+json diff --git a/swagger-spec/subjects/detail.yaml b/swagger-spec/subjects/detail.yaml new file mode 100644 index 0000000..4233ff5 --- /dev/null +++ b/swagger-spec/subjects/detail.yaml @@ -0,0 +1,87 @@ + get: + summary: Retrieve a single taxonomy subject + description: | + Retrieve detailed information about a specific taxonomy subject by its ID. + + ### Permissions + - Publicly accessible (no authentication required). + + operationId: retrieveSubject + tags: + - Subjects + parameters: + - name: subject_id + in: path + description: The unique identifier of the subject. + required: true + type: string + responses: + '200': + description: Successfully retrieved the subject. + schema: + type: object + properties: + data: + type: object + required: + - id + - type + - attributes + - relationships + properties: + id: + type: string + example: "abc123" + type: + type: string + example: "subjects" + attributes: + type: object + properties: + text: + type: string + example: "Climate Change" + taxonomy_name: + type: string + example: "OSF" + relationships: + type: object + properties: + parent: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "parent123" + type: + type: string + example: "subjects" + children: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "child123" + type: + type: string + example: "subjects" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/subjects/abc123/" + '404': + description: Subject not found. + security: + - osf_cookie: [] + produces: + - application/vnd.api+json diff --git a/swagger-spec/subjects/list.yaml b/swagger-spec/subjects/list.yaml new file mode 100644 index 0000000..1923fae --- /dev/null +++ b/swagger-spec/subjects/list.yaml @@ -0,0 +1,123 @@ +get: + summary: List available taxonomy subjects + description: | + Retrieve a list of taxonomy subjects. Subjects categorize content on the OSF. + This endpoint returns top-level subjects (those not linked to bepress subjects). + + ### Permissions + - Publicly accessible (no authentication required). + + operationId: listSubjects + tags: + - Subjects + parameters: + - name: filter[text] + in: query + description: Filter subjects by matching text. + required: false + type: string + - name: filter[parent] + in: query + description: Filter subjects by parent subject ID. + required: false + type: string + - name: page + in: query + description: Page number for paginated results. + required: false + type: integer + - name: page_size + in: query + description: Number of results per page (no max page size). + required: false + type: integer + responses: + '200': + description: Successful retrieval of subjects. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + - relationships + properties: + id: + type: string + example: "abc123" + type: + type: string + example: "subjects" + attributes: + type: object + properties: + text: + type: string + example: "Climate Change" + taxonomy_name: + type: string + example: "OSF" + relationships: + type: object + properties: + parent: + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "parent123" + type: + type: string + example: "subjects" + children: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "child123" + type: + type: string + example: "subjects" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/subjects/" + next: + type: string + example: "https://api.osf.io/v2/subjects/?page=2" + prev: + type: string + example: null + meta: + type: object + properties: + total: + type: integer + example: 100 + per_page: + type: integer + example: 10 + page: + type: integer + example: 1 + '400': + description: Bad request (e.g., invalid filter or pagination params) + security: + - osf_cookie: [] + produces: + - application/vnd.api+json \ No newline at end of file diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 20ea459..b113f74 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -35,12 +35,14 @@ x-tagGroups: tags: - Addons - Base + - CEDAR Metadata - Citations - Comments - Collections - Collection Submissions - Collection Submissions Actions - Collection Providers + - Custom Metadata - Files - Licenses - Logs @@ -57,6 +59,11 @@ x-tagGroups: - Taxonomies - Users - View Only Links + - Wikis + - Subjects + - GUIDs + - Requests + - Resources tags: - name: Introduction x-traitTag: true @@ -717,6 +724,55 @@ tags: This is the "home page" of the API you can get important autentication information for the user making the request and get links to other resources. + - name: CEDAR Metadata + description: >- + CEDAR Metadata endpoints allow you to create, read, update, and manage metadata records based on CEDAR templates. + These templates enable users to apply structured, standardized metadata to nodes and files for improved + data sharing, discoverability, and interoperability. CEDAR Metadata records are associated with OSF resources + and can be published or kept private depending on user permissions and workflow. + + - name: Custom Metadata + description: >- + Custom Metadata endpoints allow users to manage freeform or structured metadata associated with OSF nodes and files. + Unlike CEDAR metadata, Custom Metadata provides more flexible fields tailored to specific research needs or + institutional requirements. Users can create, view, and edit metadata records that describe files or items in OSF, + including funder information, language, resource type, and more. + + - name: Wikis + description: >- + The Wikis endpoints allow users to create, update, retrieve, and manage wiki pages and their versions for OSF projects + and registrations. Wikis are collaborative documents that enable teams to share information and document their + research process directly within OSF. Each wiki page maintains a version history, providing transparency and + accountability over changes. + + - name: Subjects + description: >- + Subjects endpoints provide access to the taxonomy used for categorizing OSF resources such as nodes, preprints, + and registrations. Subjects can be hierarchical, with parent and child relationships, allowing for + fine-grained classification. This enables better organization and discoverability of research content + across the OSF ecosystem. + + - name: GUIDS + description: >- + GUID endpoints resolve OSF Globally Unique Identifiers (GUIDs) to their corresponding resources, such as + nodes, users, files, registrations, preprints, and collections. These endpoints allow you to retrieve metadata + about a resource or redirect to the appropriate resource-specific endpoint for further actions. + GUIDs are a fundamental part of OSF's resource identification system. + + - name: Requests + description: >- + Requests endpoints handle formal user submissions for actions such as requesting access to private content, + withdrawal of preprints, and affiliation requests. Requests can be associated with nodes, preprints, or other + resources and go through a workflow process including approval, rejection, and moderation actions. + These endpoints facilitate transparency and control over changes and user interactions within OSF. + + - name: Resources + description: >- + Resources endpoints manage research-related resources (outcome artifacts) connected to OSF registrations. + These resources can include datasets, software, materials, papers, and supplementary files. The endpoints + support creating, retrieving, updating, and finalizing resources, making them an integral part of OSF's + open science workflow and enabling accurate documentation and discoverability of research outputs. + - name: Registration Schemas description: >- A Registration Schemas defines the range of valid responses to a registration. Each Registration @@ -854,6 +910,41 @@ tags: adheres to the standards set for collection submissions. It aids in providing transparency and order to the process of managing collections and ensures that moderators and admins have the tools and information they need to effectively manage collection submissions. + - name: Requests + description: > + Manage user-initiated requests related to nodes and preprints, including access requests, + withdrawal requests, and institutional affiliation requests. Requests are actions initiated by users + to either gain access to private content, withdraw content, or request affiliation with institutions. + Administrators and moderators can approve or reject requests, while requesters can view and comment on their submissions. + - name: Resources + description: > + Resources are structured data artifacts associated with a Registration. These can include datasets, analytic code, + materials, papers, or supplementary files that contribute to the outcomes of a study or project. Resources are part + of the registration’s metadata and support reproducibility, data sharing, and transparency in research. + + Each Resource can have an optional Persistent Identifier (PID) such as a DOI, and can be marked as finalized, + indicating it is ready for public dissemination or archival. Resources are grouped under a Registration and contribute + to Open Practice Badges when relevant artifacts are provided. + + Resources are managed through the API endpoints to: + - **Create** new resources for a Registration (e.g., data, code, papers) + - **List** existing resources linked to a Registration + - **Retrieve** details about an individual resource + - **Update** a resource’s description, type, or PID + - **Finalize** a resource to prevent further changes (once validated) + + **Note**: Once a resource is finalized, it cannot be edited or deleted. + + ### Resource Types + - `data`: Raw or processed datasets related to the research + - `analytic_code`: Code or scripts used for analysis + - `materials`: Research materials, such as instruments or questionnaires + - `papers`: Manuscripts or published papers + - `supplements`: Supplementary materials that enhance understanding of the research + + **Permissions**: + - Read access requires view permissions on the parent Registration. + - Write access requires edit permissions on the parent Registration. @@ -970,8 +1061,11 @@ paths: /institutions/{institution_id}/registrations/: $ref: 'institutions/registrations_list.yaml' - # /institutions/{institution_id}/relationships/nodes/: - # $ref: 'institutions/nodes_relationships.yaml' + /institutions/{institution_id}/relationships/nodes/: + $ref: 'institutions/relationships_nodes.yaml' + + /institutions/{institution_id}/relationships/registrations/: + $ref: 'institutions/relationships_registrations.yaml' ############################ # REGISTRATION SCHEMAS # @@ -979,6 +1073,7 @@ paths: /schemas/registrations/: $ref: 'registration_schemas/list.yaml' + /schemas/registrations/{registration_schema_id}: $ref: 'registration_schemas/detail.yaml' @@ -1232,6 +1327,15 @@ paths: /draft_registrations/{draft_id}/subjects/: $ref: 'draft_registrations/draft_registrations_subjects_list.yaml' + /draft_registrations/{draft_id}/bibliographic_contributors/: + $ref: 'draft_registrations/bibliographic_contributor_list.yaml' + + /draft_registrations/{draft_id}/relationships/institutions/: + $ref: 'draft_registrations/relationships_institutions_list.yaml' + + /draft_registrations/{draft_id}/relationships/subjects/: + $ref: 'draft_registrations/relationships_subjects_list.yaml' + ################## # TAXONOMIES # ################## @@ -1295,6 +1399,15 @@ paths: /wikis/{wiki_id}/content/: $ref: 'wikis/content.yaml' + /wikis/{wiki_id}/versions/: + $ref: 'wikis/versions_list.yaml' + + /wikis/{wiki_id}/versions/{version_id}/: + $ref: 'wikis/versions_detail.yaml' + + /wikis/{wiki_id}/versions/{version_id}/content/: + $ref: 'wikis/versions_content_list.yaml' + ################### # COLLECTIONS # ################### @@ -1376,3 +1489,64 @@ paths: /provider/collections/{collection_id}/moderators/{moderator_id}/: $ref: 'collection_provider/moderators_detail.yaml' + +####################################### +# REQUESTS # +####################################### + + /requests/{request_id}/: + $ref: 'requests/detail.yaml' + + /requests/{request_id}/actions/: + $ref: 'requests/actions_list.yaml' + +####################################### +# REQUESTS # +####################################### + + /resources/: + $ref: 'resources/list.yaml' + + /resources/{resource_id}/: + $ref: 'resources/detail.yaml' + +####################################### +# SUBJECTS # +####################################### + + /subjects/: + $ref: 'subjects/list.yaml' + + /subjects/{subject_id}/: + $ref: 'subjects/detail.yaml' + + /subjects/{subject_id}/children/: + $ref: 'subjects/children_list.yaml' + +####################################### +# GUIDS # +####################################### + + /guids/{guid_id}/: + $ref: 'guids/detail.yaml' + +####################################### +# CEDAR Metadata # +####################################### + + /files/{file_id}/cedar_metadata_records/: + $ref: 'cedar_metadata/files_list.yaml' + + /nodes/{node_id}/cedar_metadata_records/: + $ref: 'cedar_metadata/nodes_list.yaml' + +####################################### +# Custom Metadata # +####################################### + + /custom_file_metadata_records/{file_id}/: + $ref: 'cedar_metadata/files_list.yaml' + + /custom_item_metadata_records/{node_id}/: + $ref: 'cedar_metadata/nodes_list.yaml' + diff --git a/swagger-spec/wikis/content_detail.yaml b/swagger-spec/wikis/content_detail.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/wikis/versions_content_list.yaml b/swagger-spec/wikis/versions_content_list.yaml new file mode 100644 index 0000000..1e26640 --- /dev/null +++ b/swagger-spec/wikis/versions_content_list.yaml @@ -0,0 +1,45 @@ +get: + summary: Retrieve the raw content of a specific wiki version + description: | + Retrieve the plain text content of a specific version of a wiki page. + + This endpoint returns the actual content stored in the wiki page for the specified version. + The response is returned as plain text (`text/plain`). + + ### Permissions + - Public nodes: Anyone can view wiki version content. + - Private nodes: Only contributors can view wiki version content. + - Withdrawn registrations: Wiki version content is not accessible. + + tags: + - Wikis + operationId: retrieve_wiki_version_content + parameters: + - name: wiki_id + in: path + required: true + type: string + description: The unique identifier for the wiki page. + - name: version_id + in: path + required: true + type: string + description: The version identifier for the specific wiki version. + produces: + - text/plain + responses: + '200': + description: Successfully retrieved raw wiki content. + schema: + type: string + example: | + # My Wiki Page + This is the content of my wiki page in version 4. + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view this wiki version content. + '404': + description: Wiki version not found. + security: + - osf_cookie: [] diff --git a/swagger-spec/wikis/versions_detail.yaml b/swagger-spec/wikis/versions_detail.yaml new file mode 100644 index 0000000..4f54695 --- /dev/null +++ b/swagger-spec/wikis/versions_detail.yaml @@ -0,0 +1,57 @@ +get: + summary: Retrieve details for a specific wiki version + description: | + Retrieve metadata and basic details about a specific version of a wiki page. + + Wiki versions store the history of content changes and are immutable snapshots of the wiki page content at that version. + + ### Permissions + - Public nodes: Anyone can view wiki versions. + - Private nodes: Only contributors can view wiki versions. + - Withdrawn registrations: Wiki versions are not accessible. + + tags: + - Wikis + operationId: retrieve_wiki_version + parameters: + - name: wiki_id + in: path + required: true + type: string + description: The unique identifier for the wiki page. + - name: version_id + in: path + required: true + type: string + description: The version identifier for the specific wiki version. + responses: + '200': + description: Successfully retrieved the wiki version. + schema: + $ref: './definition.yaml' + examples: + application/json: + data: + id: "4" + type: "wiki-versions" + attributes: + date_created: "2024-03-10T12:00:00Z" + size: 1024 + content_type: "text/markdown" + relationships: + wiki_page: + data: + id: "abc12" + type: "wikis" + user: + data: + id: "user456" + type: "users" + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view this wiki version. + '404': + description: Wiki version not found. + security: + - osf_cookie: [] diff --git a/swagger-spec/wikis/versions_list.yaml b/swagger-spec/wikis/versions_list.yaml new file mode 100644 index 0000000..6415617 --- /dev/null +++ b/swagger-spec/wikis/versions_list.yaml @@ -0,0 +1,62 @@ +post: + summary: Create a new version of a wiki page + description: | + Create a new version of a wiki page by submitting updated content. + + This will store the updated content as a new version, incrementing the version number. + + ### Permissions + - Only contributors with write access can create new wiki versions. + - Withdrawn registrations: Cannot create new wiki versions. + + tags: + - Wikis + operationId: create_wiki_version + consumes: + - application/vnd.api+json + parameters: + - name: wiki_id + in: path + required: true + type: string + description: The unique identifier for the wiki page. + - in: body + name: body + required: true + description: The content to save in the new wiki version. + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - attributes + properties: + type: + type: string + example: wiki-versions + attributes: + type: object + required: + - content + properties: + content: + type: string + description: The new content for the wiki. + example: "This is an updated wiki page." + responses: + '201': + description: Wiki version created successfully. + schema: + $ref: './definition.yaml' + '400': + description: Invalid request payload. + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to update this wiki page. + '404': + description: Wiki page not found. From d4b6d2b886d953c00246c4005ff08bba2b1588c8 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Mon, 17 Mar 2025 14:27:57 -0400 Subject: [PATCH 10/21] add routes for registrations, nodes and preprints --- .../file_cedar_metadata_records_list.yaml | 0 .../node_cedar_metadata_records_list.yaml | 0 .../file_custom_metadata_records_detail.yaml | 0 .../node_custom_metadata_records_detail.yaml | 0 .../bibliographic_contributors_list.yaml | 0 .../relationships_institutions_list.yaml | 0 .../relationships_subjects_list.yaml | 0 swagger-spec/guids/detail.yaml | 0 swagger-spec/nodes/linked_by_nodes_list.yaml | 64 ++++ .../nodes/linked_by_registrations_list.yaml | 83 +++++ swagger-spec/nodes/node_settings_list.yaml | 208 ++++++++++++ swagger-spec/nodes/node_storage_list.yaml | 170 ++++++++++ .../relationships_institutions_list.yaml | 296 ++++++++++++++++ .../relationships_linked_nodes_list.yaml | 319 ++++++++++++++++++ ...lationships_linked_registrations_list.yaml | 319 ++++++++++++++++++ .../nodes/relationships_subjects_list.yaml | 319 ++++++++++++++++++ swagger-spec/nodes/requests_list.yaml | 160 +++++++++ swagger-spec/nodes/subjects_list.yaml | 169 ++++++++++ .../preprints/files_osfstorage_list.yaml | 98 ++++++ .../preprints/files_providers_list.yaml | 82 +++++ swagger-spec/preprints/identifiers_list.yaml | 96 ++++++ .../preprints/relationships_node.yaml | 171 ++++++++++ swagger-spec/preprints/requests_list.yaml | 139 ++++++++ .../preprints/review_actions_list.yaml | 192 +++++++++++ swagger-spec/preprints/subjects_list.yaml | 115 +++++++ swagger-spec/preprints/versions_list.yaml | 156 +++++++++ swagger-spec/registrations/actions_list.yaml | 71 ++++ .../bibliographic_contributors_list.yaml | 156 +++++++++ .../cedar_metadata_records_list.yaml | 163 +++++++++ ...detail.yaml => citation_style_detail.yaml} | 0 ...yle_list.yaml => citation_style_list.yaml} | 0 .../implicit_contributors_list.yaml | 143 ++++++++ .../registrations/linked_by_nodes_list.yaml | 134 ++++++++ .../linked_by_registrations_list.yaml | 134 ++++++++ .../registrations/node_links_detail.yaml | 0 .../registrations/node_links_list.yaml | 137 ++++++++ .../registrations/registrations_list.yaml | 147 ++++++++ .../relationships_institutions_list.yaml | 77 +++++ .../relationships_linked_nodes_list.yaml | 81 +++++ ...lationships_linked_registrations_list.yaml | 80 +++++ .../relationships_subjects_list.yaml | 77 +++++ swagger-spec/registrations/requests_list.yaml | 81 +++++ .../registrations/resources_list.yaml | 70 ++++ .../registrations/schema_responses_list.yaml | 86 +++++ swagger-spec/registrations/subjects_list.yaml | 80 +++++ swagger-spec/requests/actions_list.yaml | 0 swagger-spec/requests/definition.yaml | 0 swagger-spec/requests/detail.yaml | 0 swagger-spec/resources/definition.yaml | 0 swagger-spec/resources/detail.yaml | 0 swagger-spec/resources/list.yaml | 0 swagger-spec/swagger.yaml | 112 +++++- 52 files changed, 4983 insertions(+), 2 deletions(-) create mode 100644 swagger-spec/cedar_metadata_records/file_cedar_metadata_records_list.yaml create mode 100644 swagger-spec/cedar_metadata_records/node_cedar_metadata_records_list.yaml create mode 100644 swagger-spec/custom_file_metadata_records/file_custom_metadata_records_detail.yaml create mode 100644 swagger-spec/custom_file_metadata_records/node_custom_metadata_records_detail.yaml create mode 100644 swagger-spec/draft_registrations/bibliographic_contributors_list.yaml create mode 100644 swagger-spec/draft_registrations/relationships_institutions_list.yaml create mode 100644 swagger-spec/draft_registrations/relationships_subjects_list.yaml create mode 100644 swagger-spec/guids/detail.yaml create mode 100644 swagger-spec/nodes/linked_by_nodes_list.yaml create mode 100644 swagger-spec/nodes/linked_by_registrations_list.yaml create mode 100644 swagger-spec/nodes/node_settings_list.yaml create mode 100644 swagger-spec/nodes/node_storage_list.yaml create mode 100644 swagger-spec/nodes/relationships_institutions_list.yaml create mode 100644 swagger-spec/nodes/relationships_linked_nodes_list.yaml create mode 100644 swagger-spec/nodes/relationships_linked_registrations_list.yaml create mode 100644 swagger-spec/nodes/relationships_subjects_list.yaml create mode 100644 swagger-spec/nodes/requests_list.yaml create mode 100644 swagger-spec/nodes/subjects_list.yaml create mode 100644 swagger-spec/preprints/files_osfstorage_list.yaml create mode 100644 swagger-spec/preprints/files_providers_list.yaml create mode 100644 swagger-spec/preprints/identifiers_list.yaml create mode 100644 swagger-spec/preprints/relationships_node.yaml create mode 100644 swagger-spec/preprints/requests_list.yaml create mode 100644 swagger-spec/preprints/review_actions_list.yaml create mode 100644 swagger-spec/preprints/subjects_list.yaml create mode 100644 swagger-spec/preprints/versions_list.yaml create mode 100644 swagger-spec/registrations/actions_list.yaml create mode 100644 swagger-spec/registrations/bibliographic_contributors_list.yaml create mode 100644 swagger-spec/registrations/cedar_metadata_records_list.yaml rename swagger-spec/registrations/{style_detail.yaml => citation_style_detail.yaml} (100%) rename swagger-spec/registrations/{style_list.yaml => citation_style_list.yaml} (100%) create mode 100644 swagger-spec/registrations/implicit_contributors_list.yaml create mode 100644 swagger-spec/registrations/linked_by_nodes_list.yaml create mode 100644 swagger-spec/registrations/linked_by_registrations_list.yaml create mode 100644 swagger-spec/registrations/node_links_detail.yaml create mode 100644 swagger-spec/registrations/node_links_list.yaml create mode 100644 swagger-spec/registrations/registrations_list.yaml create mode 100644 swagger-spec/registrations/relationships_institutions_list.yaml create mode 100644 swagger-spec/registrations/relationships_linked_nodes_list.yaml create mode 100644 swagger-spec/registrations/relationships_linked_registrations_list.yaml create mode 100644 swagger-spec/registrations/relationships_subjects_list.yaml create mode 100644 swagger-spec/registrations/requests_list.yaml create mode 100644 swagger-spec/registrations/resources_list.yaml create mode 100644 swagger-spec/registrations/schema_responses_list.yaml create mode 100644 swagger-spec/registrations/subjects_list.yaml create mode 100644 swagger-spec/requests/actions_list.yaml create mode 100644 swagger-spec/requests/definition.yaml create mode 100644 swagger-spec/requests/detail.yaml create mode 100644 swagger-spec/resources/definition.yaml create mode 100644 swagger-spec/resources/detail.yaml create mode 100644 swagger-spec/resources/list.yaml diff --git a/swagger-spec/cedar_metadata_records/file_cedar_metadata_records_list.yaml b/swagger-spec/cedar_metadata_records/file_cedar_metadata_records_list.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/cedar_metadata_records/node_cedar_metadata_records_list.yaml b/swagger-spec/cedar_metadata_records/node_cedar_metadata_records_list.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/custom_file_metadata_records/file_custom_metadata_records_detail.yaml b/swagger-spec/custom_file_metadata_records/file_custom_metadata_records_detail.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/custom_file_metadata_records/node_custom_metadata_records_detail.yaml b/swagger-spec/custom_file_metadata_records/node_custom_metadata_records_detail.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/draft_registrations/bibliographic_contributors_list.yaml b/swagger-spec/draft_registrations/bibliographic_contributors_list.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/draft_registrations/relationships_institutions_list.yaml b/swagger-spec/draft_registrations/relationships_institutions_list.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/draft_registrations/relationships_subjects_list.yaml b/swagger-spec/draft_registrations/relationships_subjects_list.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/guids/detail.yaml b/swagger-spec/guids/detail.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/nodes/linked_by_nodes_list.yaml b/swagger-spec/nodes/linked_by_nodes_list.yaml new file mode 100644 index 0000000..c925b89 --- /dev/null +++ b/swagger-spec/nodes/linked_by_nodes_list.yaml @@ -0,0 +1,64 @@ + get: + summary: List Nodes Linking to a Node + description: >- + Retrieve a list of nodes that link to the specified node. + + #### Permissions + - Public nodes are visible to everyone. + - Private nodes require appropriate permissions to access. + - The authenticated user must have read access to see restricted nodes linking to this node. + + #### Returns + - A paginated list of nodes that link to the specified node. + + tags: + - Nodes + + operationId: node_linked_by_nodes_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node to look up linked nodes for. + responses: + '200': + description: A paginated list of nodes linking to the specified node. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results. + prev: + type: string + description: Link to the previous page of results. + meta: + type: object + properties: + total: + type: integer + description: Total number of nodes linking to this node. + per_page: + type: integer + description: Number of results per page. + + '401': + description: Unauthorized. Authentication is required. + + '403': + description: Forbidden. You do not have permission to view nodes linking to this node. + + '404': + description: Not Found. No node matches the given ID. \ No newline at end of file diff --git a/swagger-spec/nodes/linked_by_registrations_list.yaml b/swagger-spec/nodes/linked_by_registrations_list.yaml new file mode 100644 index 0000000..443b168 --- /dev/null +++ b/swagger-spec/nodes/linked_by_registrations_list.yaml @@ -0,0 +1,83 @@ +get: + summary: List Registrations Linking to a Node + description: >- + Retrieve a list of registrations that have created links to the specified node. + + #### Permissions + - Public registrations are visible to everyone. + - Registrations with restricted visibility require appropriate permissions to access. + - The authenticated user must have read access to see restricted registrations linking to this node. + + #### Returns + - A paginated list of registrations that link to the specified node. + + tags: + - Nodes + + operationId: node_linked_by_registrations_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node to look up linked registrations for. + + - in: query + name: page + type: integer + description: Page number of the results to return (pagination). + + - in: query + name: filter + type: string + description: Filter results by registration attributes (e.g., `filter[title]=example`). + + - in: query + name: sort + type: string + description: | + Sort the returned registrations. + - `date_created`: Sort by creation date. + - `title`: Sort alphabetically by title. + + responses: + '200': + description: A paginated list of registrations linking to the node. + schema: + type: object + properties: + data: + type: array + items: + $ref: '../registrations/definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results. + prev: + type: string + description: Link to the previous page of results. + meta: + type: object + properties: + total: + type: integer + description: Total number of registrations linking to this node. + per_page: + type: integer + description: Number of results per page. + + '401': + description: Unauthorized. Authentication is required. + + '403': + description: Forbidden. You do not have permission to view registrations linking to this node. + + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/nodes/node_settings_list.yaml b/swagger-spec/nodes/node_settings_list.yaml new file mode 100644 index 0000000..52fae9f --- /dev/null +++ b/swagger-spec/nodes/node_settings_list.yaml @@ -0,0 +1,208 @@ +get: + summary: Retrieve Node Settings + description: >- + Retrieve the settings for a specific node. + This includes details such as whether wiki functionality is enabled, if comments are enabled, and other configurable settings. + + #### Permissions + - Public nodes expose a subset of settings. + - Private nodes require read permissions to view full settings. + + #### Returns + - A JSON object with a `data` key containing the node's settings. + + tags: + - Nodes + + operationId: node_settings_read + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + responses: + '200': + description: Successfully retrieved node settings. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + description: The unique identifier of the node settings object (same as node_id). + type: + type: string + example: "node-settings" + attributes: + type: object + properties: + wiki_enabled: + type: boolean + description: Whether the node has the wiki feature enabled. + example: true + comments_enabled: + type: boolean + description: Whether comments are enabled on the node. + example: true + public: + type: boolean + description: Whether the node is public or private. + example: false + preprint: + type: boolean + description: Whether this node is designated as a preprint. + example: false + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/settings/" + + examples: + application/json: + data: + id: "{node_id}" + type: "node-settings" + attributes: + wiki_enabled: true + comments_enabled: true + public: false + preprint: false + links: + self: "https://api.osf.io/v2/nodes/{node_id}/settings/" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access node settings. + '404': + description: Not Found. No node matches the given ID. + +patch: + summary: Update Node Settings + description: >- + Update settings for a specific node. + You can modify properties like `wiki_enabled`, `comments_enabled`, or make the node public/private. + + #### Permissions + - Only users with write access to the node can modify its settings. + + #### Request Body + - The `attributes` object may include the following fields: + - `wiki_enabled`: Enable or disable the node's wiki. + - `comments_enabled`: Enable or disable comments on the node. + - `public`: Make the node public or private. + + #### Returns + - A JSON object with the updated node settings under the `data` key. + + tags: + - Nodes + + operationId: node_settings_update + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + description: The unique identifier of the node settings object (same as node_id). + type: + type: string + enum: + - node-settings + attributes: + type: object + properties: + wiki_enabled: + type: boolean + description: Enable or disable the node's wiki. + comments_enabled: + type: boolean + description: Enable or disable comments on the node. + public: + type: boolean + description: Make the node public or private. + + example: + data: + id: "{node_id}" + type: "node-settings" + attributes: + wiki_enabled: false + comments_enabled: false + public: true + + responses: + '200': + description: Node settings successfully updated. + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + type: + type: string + example: "node-settings" + attributes: + type: object + properties: + wiki_enabled: + type: boolean + comments_enabled: + type: boolean + public: + type: boolean + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/settings/" + + examples: + application/json: + data: + id: "{node_id}" + type: "node-settings" + attributes: + wiki_enabled: false + comments_enabled: false + public: true + links: + self: "https://api.osf.io/v2/nodes/{node_id}/settings/" + + '400': + description: Bad Request. Invalid input was provided. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify node settings. + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/nodes/node_storage_list.yaml b/swagger-spec/nodes/node_storage_list.yaml new file mode 100644 index 0000000..00ee102 --- /dev/null +++ b/swagger-spec/nodes/node_storage_list.yaml @@ -0,0 +1,170 @@ +get: + summary: List Storage Providers for a Node + description: >- + Retrieve the list of storage providers associated with a specific node. + Each node in the OSF automatically has an OSF Storage provider, and may have additional third-party storage providers (such as Dropbox or Google Drive) if configured. + + #### Permissions + - Public nodes expose storage provider information publicly. + - Private nodes require read permissions to access storage providers. + + #### Returns + - A JSON object with a `data` array containing storage provider resources assigned to the node. + + tags: + - Nodes + + operationId: node_storage_providers_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: query + name: page + type: integer + description: Page number of results to retrieve. + + - in: query + name: embed + type: string + description: Comma-separated list of related resources to embed in the response. + + responses: + '200': + description: Successful retrieval of storage providers for the specified node. + schema: + type: object + properties: + data: + type: array + description: List of storage providers assigned to the node. + items: + type: object + properties: + id: + type: string + description: Unique identifier for the storage provider. + example: "osfstorage" + type: + type: string + description: The resource type. + example: "providers" + attributes: + type: object + properties: + name: + type: string + description: The name of the storage provider. + example: "OSF Storage" + default: + type: boolean + description: Whether this provider is the default storage location for the node. + example: true + capability: + type: array + description: List of capabilities supported by the provider (e.g., upload, delete). + items: + type: string + example: "upload" + regions: + type: array + description: Available regions (if applicable). + items: + type: string + example: "us-east-1" + + relationships: + type: object + description: Related resources. + properties: + files: + description: Files stored within this provider. + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/files/{provider}/" + + links: + type: object + properties: + self: + type: string + description: Canonical link to this storage provider. + example: "https://api.osf.io/v2/nodes/{node_id}/files/providers/osfstorage/" + + links: + type: object + description: Pagination links for the result set. + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/storage/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/storage/?page=1" + last: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/storage/?page=1" + + meta: + type: object + description: Meta information about the response. + properties: + total: + type: integer + description: Total number of storage providers available for this node. + example: 1 + per_page: + type: integer + description: Number of results per page. + example: 10 + + examples: + application/json: + data: + - id: "osfstorage" + type: "providers" + attributes: + name: "OSF Storage" + default: true + capability: + - "upload" + - "delete" + regions: + - "us-east-1" + relationships: + files: + links: + related: "https://api.osf.io/v2/nodes/abc12/files/osfstorage/" + links: + self: "https://api.osf.io/v2/nodes/abc12/files/providers/osfstorage/" + links: + self: "https://api.osf.io/v2/nodes/abc12/storage/" + next: null + prev: null + first: "https://api.osf.io/v2/nodes/abc12/storage/?page=1" + last: "https://api.osf.io/v2/nodes/abc12/storage/?page=1" + meta: + total: 1 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view storage providers for this node. + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/nodes/relationships_institutions_list.yaml b/swagger-spec/nodes/relationships_institutions_list.yaml new file mode 100644 index 0000000..c4e078a --- /dev/null +++ b/swagger-spec/nodes/relationships_institutions_list.yaml @@ -0,0 +1,296 @@ +get: + summary: Retrieve relationships between a Node and its affiliated Institutions + description: >- + Retrieve a list of resource identifier objects that represent the institutions affiliated with the given node. + + #### Permissions + - Public nodes will display their affiliated institutions. + - Private nodes require read permissions. + + #### Returns + - A JSON object with a `data` key containing an array of resource identifier objects (`type` and `id`) for each affiliated institution. + + tags: + - Nodes + + operationId: node_relationships_institutions_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + responses: + '200': + description: Successfully retrieved affiliated institutions for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "institutions" + id: + type: string + example: "cos" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/relationships/institutions/" + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/institutions/" + examples: + application/json: + data: + - type: "institutions" + id: "cos" + - type: "institutions" + id: "uva" + links: + self: "https://api.osf.io/v2/nodes/{node_id}/relationships/institutions/" + related: "https://api.osf.io/v2/nodes/{node_id}/institutions/" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view institutions for this node. + '404': + description: Not Found. No node matches the given ID. + +patch: + summary: Replace relationships between a Node and its affiliated Institutions + description: >- + Replace all existing affiliated institutions for a node with a new set of institutions. + + #### Permissions + - The authenticated user must have admin permissions on the node. + + #### Request Body + - A `data` array containing the new list of institution resource identifier objects (`type` and `id`). + + #### Returns + - The updated list of affiliated institutions for the node. + + tags: + - Nodes + + operationId: node_relationships_institutions_update + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - institutions + description: Must be `institutions`. + id: + type: string + description: The unique identifier of the institution. + example: + data: + - type: "institutions" + id: "cos" + + responses: + '200': + description: Successfully replaced affiliated institutions for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: institutions + id: + type: string + example: cos + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify institutions for this node. + '404': + description: Not Found. No node matches the given ID. + +post: + summary: Add relationships between a Node and Institutions + description: >- + Add new affiliated institutions to the node, while keeping the existing ones intact. + + #### Permissions + - The authenticated user must have admin permissions on the node. + + #### Request Body + - A `data` array containing additional institution resource identifier objects to be added. + + #### Returns + - The updated list of affiliated institutions for the node. + + tags: + - Nodes + + operationId: node_relationships_institutions_add + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - institutions + description: Must be `institutions`. + id: + type: string + description: The unique identifier for the institution. + example: + data: + - type: "institutions" + id: "uva" + + responses: + '200': + description: Successfully added affiliated institutions to the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "institutions" + id: + type: string + example: "uva" + examples: + application/json: + data: + - type: "institutions" + id: "cos" + - type: "institutions" + id: "uva" + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify institutions for this node. + '404': + description: Not Found. No node matches the given ID. + +delete: + summary: Remove relationships between a Node and Institutions + description: >- + Remove specified affiliated institutions from the node. + + #### Permissions + - The authenticated user must have admin permissions on the node. + + #### Request Body + - A `data` array containing the institution resource identifier objects to be removed. + + #### Returns + - An empty response indicating successful deletion. + + tags: + - Nodes + + operationId: node_relationships_institutions_delete + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - institutions + description: Must be `institutions`. + id: + type: string + description: The unique identifier for the institution. + example: + data: + - type: "institutions" + id: "cos" + + responses: + '204': + description: Successfully removed affiliated institutions from the node. No content returned. + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify institutions for this node. + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/nodes/relationships_linked_nodes_list.yaml b/swagger-spec/nodes/relationships_linked_nodes_list.yaml new file mode 100644 index 0000000..d7974aa --- /dev/null +++ b/swagger-spec/nodes/relationships_linked_nodes_list.yaml @@ -0,0 +1,319 @@ +get: + summary: Retrieve relationships between a Node and its linked Nodes + description: >- + Retrieve a list of resource identifier objects that represent the nodes linked to the given node. + + #### Permissions + - Public nodes will display their public linked nodes. + - Private nodes require read permissions. + + #### Returns + - A JSON object with a `data` key containing an array of resource identifier objects (`type` and `id`) for each linked node. + + tags: + - Nodes + + operationId: node_relationships_linked_nodes_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + responses: + '200': + description: Successfully retrieved linked nodes for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "nodes" + id: + type: string + example: "abc123" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/relationships/linked_nodes/" + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/linked_nodes/" + examples: + application/json: + data: + - type: "nodes" + id: "abc123" + - type: "nodes" + id: "def456" + links: + self: "https://api.osf.io/v2/nodes/{node_id}/relationships/linked_nodes/" + related: "https://api.osf.io/v2/nodes/{node_id}/linked_nodes/" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view linked nodes for this node. + '404': + description: Not Found. No node matches the given ID. + +patch: + summary: Replace relationships between a Node and its linked Nodes + description: >- + Replace all existing linked nodes for a node with a new set of linked nodes. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing the new list of node resource identifier objects (`type` and `id`). + + #### Returns + - The updated list of linked nodes for the node. + + tags: + - Nodes + + operationId: node_relationships_linked_nodes_update + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - nodes + description: Must be `nodes`. + id: + type: string + description: The unique identifier for the node. + example: + data: + - type: "nodes" + id: "abc123" + - type: "nodes" + id: "def456" + + responses: + '200': + description: Successfully replaced linked nodes for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "nodes" + id: + type: string + example: "node_id" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/relationships/linked_nodes/" + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/linked_nodes/" + examples: + application/json: + data: + - type: "nodes" + id: "abc123" + - type: "nodes" + id: "def456" + links: + self: "https://api.osf.io/v2/nodes/{node_id}/relationships/linked_nodes/" + related: "https://api.osf.io/v2/nodes/{node_id}/linked_nodes/" + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify linked nodes for this node. + '404': + description: Not Found. No node matches the given ID. + +post: + summary: Add relationships between a Node and linked Nodes + description: >- + Add new linked nodes to the node, while keeping the existing ones intact. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing additional node resource identifier objects to be added. + + #### Returns + - The updated list of linked nodes for the node. + + tags: + - Nodes + + operationId: node_relationships_linked_nodes_add + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - nodes + description: Must be `nodes`. + id: + type: string + description: The unique identifier for the node. + example: + data: + - type: "nodes" + id: "ghi789" + + responses: + '200': + description: Successfully added linked nodes to the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "nodes" + id: + type: string + example: "node_id" + examples: + application/json: + data: + - type: "nodes" + id: "abc123" + - type: "nodes" + id: "def456" + - type: "nodes" + id: "ghi789" + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify linked nodes for this node. + '404': + description: Not Found. No node matches the given ID. + +delete: + summary: Remove relationships between a Node and linked Nodes + description: >- + Remove specified linked nodes from the node. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing the node resource identifier objects to be removed. + + #### Returns + - An empty response indicating successful deletion. + + tags: + - Nodes + + operationId: node_relationships_linked_nodes_delete + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - nodes + description: Must be `nodes`. + id: + type: string + description: The unique identifier for the node. + example: + data: + - type: "nodes" + id: "abc123" + + responses: + '204': + description: Successfully removed linked nodes from the node. No content returned. + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify linked nodes for this node. + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/nodes/relationships_linked_registrations_list.yaml b/swagger-spec/nodes/relationships_linked_registrations_list.yaml new file mode 100644 index 0000000..d9564ff --- /dev/null +++ b/swagger-spec/nodes/relationships_linked_registrations_list.yaml @@ -0,0 +1,319 @@ +get: + summary: Retrieve relationships between a Node and its linked Registrations + description: >- + Retrieve a list of resource identifier objects that represent the registrations linked to the given node. + + #### Permissions + - Public nodes will show public linked registrations. + - Private nodes require read permissions. + + #### Returns + - A JSON object with a `data` key containing an array of resource identifier objects (`type` and `id`) for each linked registration. + + tags: + - Nodes + + operationId: node_relationships_linked_registrations_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + responses: + '200': + description: Successfully retrieved linked registrations for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "registrations" + id: + type: string + example: "registration_id" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/relationships/linked_registrations/" + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/linked_registrations/" + examples: + application/json: + data: + - type: "registrations" + id: "abc123" + - type: "registrations" + id: "def456" + links: + self: "https://api.osf.io/v2/nodes/{node_id}/relationships/linked_registrations/" + related: "https://api.osf.io/v2/nodes/{node_id}/linked_registrations/" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view linked registrations for this node. + '404': + description: Not Found. No node matches the given ID. + +patch: + summary: Replace relationships between a Node and linked Registrations + description: >- + Replace all existing linked registrations for a node with a new set of linked registrations. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing the new list of registration resource identifier objects (`type` and `id`). + + #### Returns + - The updated list of linked registrations for the node. + + tags: + - Nodes + + operationId: node_relationships_linked_registrations_update + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - registrations + description: Must be `registrations`. + id: + type: string + description: The unique identifier for the registration. + example: + data: + - type: "registrations" + id: "abc123" + - type: "registrations" + id: "def456" + + responses: + '200': + description: Successfully replaced linked registrations for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "registrations" + id: + type: string + example: "registration_id" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/relationships/linked_registrations/" + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/linked_registrations/" + examples: + application/json: + data: + - type: "registrations" + id: "abc123" + - type: "registrations" + id: "def456" + links: + self: "https://api.osf.io/v2/nodes/{node_id}/relationships/linked_registrations/" + related: "https://api.osf.io/v2/nodes/{node_id}/linked_registrations/" + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify linked registrations for this node. + '404': + description: Not Found. No node matches the given ID. + +post: + summary: Add relationships between a Node and linked Registrations + description: >- + Add new linked registrations to the node, while keeping the existing ones intact. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing additional registration resource identifier objects to be added. + + #### Returns + - The updated list of linked registrations for the node. + + tags: + - Nodes + + operationId: node_relationships_linked_registrations_add + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - registrations + description: Must be `registrations`. + id: + type: string + description: The unique identifier for the registration. + example: + data: + - type: "registrations" + id: "ghi789" + + responses: + '200': + description: Successfully added linked registrations to the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "registrations" + id: + type: string + example: "registration_id" + examples: + application/json: + data: + - type: "registrations" + id: "abc123" + - type: "registrations" + id: "def456" + - type: "registrations" + id: "ghi789" + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify linked registrations for this node. + '404': + description: Not Found. No node matches the given ID. + +delete: + summary: Remove relationships between a Node and linked Registrations + description: >- + Remove specified linked registrations from the node. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing the registration resource identifier objects to be removed. + + #### Returns + - An empty response indicating successful deletion. + + tags: + - Nodes + + operationId: node_relationships_linked_registrations_delete + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - registrations + description: Must be `registrations`. + id: + type: string + description: The unique identifier for the registration. + example: + data: + - type: "registrations" + id: "abc123" + + responses: + '204': + description: Successfully removed linked registrations from the node. No content returned. + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify linked registrations for this node. + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/nodes/relationships_subjects_list.yaml b/swagger-spec/nodes/relationships_subjects_list.yaml new file mode 100644 index 0000000..c2bb9d5 --- /dev/null +++ b/swagger-spec/nodes/relationships_subjects_list.yaml @@ -0,0 +1,319 @@ +get: + summary: Retrieve the relationships between a Node and its Subjects + description: >- + Retrieve a list of relationship identifiers (resource linkage) representing the subjects associated with a specific node. + + #### Permissions + - Public nodes will display public subjects. + - Private nodes require read permissions. + + #### Returns + - A JSON object with a `data` key containing an array of resource identifier objects (`type` and `id`) for each subject linked to the node. + + tags: + - Nodes + + operationId: node_relationships_subjects_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + responses: + '200': + description: Successfully retrieved the subject relationships for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "subjects" + id: + type: string + example: "subject_id" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/relationships/subjects/" + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/subjects/" + examples: + application/json: + data: + - type: "subjects" + id: "abc123" + - type: "subjects" + id: "def456" + links: + self: "https://api.osf.io/v2/nodes/{node_id}/relationships/subjects/" + related: "https://api.osf.io/v2/nodes/{node_id}/subjects/" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view subjects on this node. + '404': + description: Not Found. No node matches the given ID. + +patch: + summary: Update the relationships between a Node and its Subjects + description: >- + Replace all existing subject relationships on a node with a new list of subjects. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing the new list of subject resource identifier objects (`type` and `id`). + + #### Returns + - The updated list of subject relationships for the node. + + tags: + - Nodes + + operationId: node_relationships_subjects_update + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - subjects + description: Must be `subjects`. + id: + type: string + description: The unique identifier for the subject. + example: + data: + - type: "subjects" + id: "abc123" + - type: "subjects" + id: "def456" + + responses: + '200': + description: Successfully updated the subject relationships for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "subjects" + id: + type: string + example: "subject_id" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/relationships/subjects/" + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/subjects/" + examples: + application/json: + data: + - type: "subjects" + id: "abc123" + - type: "subjects" + id: "def456" + links: + self: "https://api.osf.io/v2/nodes/{node_id}/relationships/subjects/" + related: "https://api.osf.io/v2/nodes/{node_id}/subjects/" + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify subjects on this node. + '404': + description: Not Found. No node matches the given ID. + +post: + summary: Add relationships between a Node and Subjects + description: >- + Add new subject relationships to a node, keeping the existing subjects intact. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing additional subject resource identifier objects to be added. + + #### Returns + - The updated list of subject relationships for the node. + + tags: + - Nodes + + operationId: node_relationships_subjects_add + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - subjects + description: Must be `subjects`. + id: + type: string + description: The unique identifier for the subject. + example: + data: + - type: "subjects" + id: "ghi789" + + responses: + '200': + description: Successfully added subjects to the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + type: + type: string + example: "subjects" + id: + type: string + example: "subject_id" + examples: + application/json: + data: + - type: "subjects" + id: "abc123" + - type: "subjects" + id: "def456" + - type: "subjects" + id: "ghi789" + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify subjects on this node. + '404': + description: Not Found. No node matches the given ID. + +delete: + summary: Remove relationships between a Node and Subjects + description: >- + Remove specified subject relationships from a node. + + #### Permissions + - The authenticated user must have write permissions on the node. + + #### Request Body + - A `data` array containing the subject resource identifier objects to be removed. + + #### Returns + - An empty response indicating successful deletion. + + tags: + - Nodes + + operationId: node_relationships_subjects_delete + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - subjects + description: Must be `subjects`. + id: + type: string + description: The unique identifier for the subject. + example: + data: + - type: "subjects" + id: "abc123" + + responses: + '204': + description: Successfully deleted the subject relationship(s) from the node. No content returned. + '400': + description: Bad Request. The submitted data is invalid. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify subjects on this node. + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/nodes/requests_list.yaml b/swagger-spec/nodes/requests_list.yaml new file mode 100644 index 0000000..77ee668 --- /dev/null +++ b/swagger-spec/nodes/requests_list.yaml @@ -0,0 +1,160 @@ +get: + summary: List Requests for a Node + description: >- + Retrieve a list of requests associated with a specific node. + Requests include actions such as registration approval, withdrawal, or other moderation-related requests initiated on the node. + + #### Permissions + - The authenticated user must have read access to the node to view its requests. + - Moderators or admins of the provider may have additional access to request details depending on their role. + + #### Returns + - A JSON object with a `data` key containing a list of request resources. + - Each request provides metadata about its current state, type, creator, and review process. + + tags: + - Nodes + + operationId: node_requests_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: query + name: filter[type] + type: string + description: Filter requests by type (e.g., `withdrawal`, `registration`). + + - in: query + name: filter[state] + type: string + description: Filter requests by current state (e.g., `pending`, `accepted`, `rejected`). + + responses: + '200': + description: Successfully retrieved the list of requests for the node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier for the request. + type: + type: string + example: "requests" + attributes: + type: object + properties: + request_type: + type: string + description: The type of the request, such as `withdrawal` or `registration`. + example: "withdrawal" + state: + type: string + description: The current state of the request. + example: "pending" + created: + type: string + format: date-time + description: The timestamp when the request was created. + example: "2024-03-10T15:30:00Z" + modified: + type: string + format: date-time + description: The timestamp when the request was last modified. + example: "2024-03-12T10:00:00Z" + relationships: + type: object + properties: + creator: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/users/{user_id}/" + data: + type: object + properties: + type: + type: string + example: "users" + id: + type: string + example: "user_id" + target: + type: object + properties: + links: + type: object + properties: + related: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/" + data: + type: object + properties: + type: + type: string + example: "nodes" + id: + type: string + example: "node_id" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/requests/{request_id}/" + meta: + type: object + properties: + total: + type: integer + example: 1 + + examples: + application/json: + data: + - id: "abc123" + type: "requests" + attributes: + request_type: "withdrawal" + state: "pending" + created: "2024-03-10T15:30:00Z" + modified: "2024-03-12T10:00:00Z" + relationships: + creator: + links: + related: "https://api.osf.io/v2/users/user1/" + data: + type: "users" + id: "user1" + target: + links: + related: "https://api.osf.io/v2/nodes/{node_id}/" + data: + type: "nodes" + id: "{node_id}" + links: + self: "https://api.osf.io/v2/requests/abc123/" + meta: + total: 1 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access requests for this node. + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/nodes/subjects_list.yaml b/swagger-spec/nodes/subjects_list.yaml new file mode 100644 index 0000000..7de32fe --- /dev/null +++ b/swagger-spec/nodes/subjects_list.yaml @@ -0,0 +1,169 @@ +get: + summary: List Subjects for a Node + description: >- + Retrieve the list of taxonomy subjects assigned to a specific node. + Subjects represent thematic classifications for the content of a node. + A node can have multiple subjects, typically applied in the context of preprints or projects associated with specific disciplines. + + #### Permissions + - Public nodes expose subjects publicly. + - Private nodes require read permissions to access subjects. + + #### Returns + - A JSON object with a `data` array containing subject resources assigned to the node. + + tags: + - Nodes + + operationId: node_subjects_list + + parameters: + - in: path + name: node_id + type: string + required: true + description: The unique identifier of the node. + + - in: query + name: page + type: integer + description: Page number of results to retrieve. + + - in: query + name: filter + type: string + description: | + Filter subjects by specific fields. + Example: `filter[text]=biology` + + - in: query + name: embed + type: string + description: Comma-separated list of related resources to embed in the response. + + responses: + '200': + description: Successful retrieval of subjects for the specified node. + schema: + type: object + properties: + data: + type: array + description: List of subjects assigned to the node. + items: + type: object + properties: + id: + type: string + description: Unique identifier for the subject. + example: "12345" + type: + type: string + description: The resource type. + example: "subjects" + attributes: + type: object + properties: + text: + type: string + description: The human-readable text of the subject. + example: "Biology" + parent_ids: + type: array + description: List of parent subject IDs (for hierarchical subjects). + items: + type: string + example: "6789" + has_children: + type: boolean + description: Whether the subject has child subjects. + example: false + relationships: + type: object + properties: + parent: + description: Parent subject of this subject. + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "6789" + type: + type: string + example: "subjects" + links: + type: object + properties: + self: + type: string + description: Canonical link to this subject. + example: "https://api.osf.io/v2/taxonomies/12345/" + + links: + type: object + description: Pagination links for the result set. + properties: + self: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/subjects/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/subjects/?page=1" + last: + type: string + example: "https://api.osf.io/v2/nodes/{node_id}/subjects/?page=1" + + meta: + type: object + description: Meta information about the response. + properties: + total: + type: integer + description: Total number of subjects assigned to the node. + example: 3 + per_page: + type: integer + description: Number of results per page. + example: 10 + + examples: + application/json: + data: + - id: "12345" + type: "subjects" + attributes: + text: "Biology" + parent_ids: ["0001"] + has_children: false + relationships: + parent: + data: + id: "0001" + type: "subjects" + links: + self: "https://api.osf.io/v2/taxonomies/12345/" + links: + self: "https://api.osf.io/v2/nodes/abc12/subjects/" + next: null + prev: null + first: "https://api.osf.io/v2/nodes/abc12/subjects/?page=1" + last: "https://api.osf.io/v2/nodes/abc12/subjects/?page=1" + meta: + total: 1 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view subjects for this node. + '404': + description: Not Found. No node matches the given ID. diff --git a/swagger-spec/preprints/files_osfstorage_list.yaml b/swagger-spec/preprints/files_osfstorage_list.yaml new file mode 100644 index 0000000..87aba0b --- /dev/null +++ b/swagger-spec/preprints/files_osfstorage_list.yaml @@ -0,0 +1,98 @@ +get: + summary: List files for a preprint in osfstorage + description: >- + Retrieve a list of files stored in the `osfstorage` provider for the specified preprint. + Only "osfstorage" is available for preprints. + + #### Permissions + - Public files are accessible to unauthenticated users. + - Viewing non-public files requires appropriate permissions. + + tags: + - Preprints + - Files + + operationId: preprint_files_list + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint. + + responses: + '200': + description: Successful retrieval of files in osfstorage. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + - links + properties: + id: + type: string + description: The ID of the file. + example: 5b8df35e8c7d2e001d6fa3f9 + type: + type: string + example: files + attributes: + type: object + properties: + name: + type: string + description: The name of the file. + example: paper.pdf + kind: + type: string + description: Type of the file object ('file' or 'folder'). + example: file + size: + type: integer + description: Size of the file in bytes. + example: 102400 + modified: + type: string + format: date-time + description: Last modified date of the file. + example: "2023-09-01T12:00:00Z" + contentType: + type: string + description: MIME type of the file. + example: application/pdf + links: + type: object + properties: + download: + type: string + description: URL to download the file. + upload: + type: string + description: URL to upload new versions of the file. + example: + data: + - id: 5b8df35e8c7d2e001d6fa3f9 + type: files + attributes: + name: paper.pdf + kind: file + size: 102400 + modified: "2023-09-01T12:00:00Z" + contentType: application/pdf + links: + download: https://files.osf.io/v1/resources/abc12/providers/osfstorage/5b8df35e8c7d2e001d6fa3f9 + upload: https://files.osf.io/v1/resources/abc12/providers/osfstorage/5b8df35e8c7d2e001d6fa3f9 + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view these files. + '404': + description: Not Found. No preprint matches the given ID. \ No newline at end of file diff --git a/swagger-spec/preprints/files_providers_list.yaml b/swagger-spec/preprints/files_providers_list.yaml new file mode 100644 index 0000000..4a8da5a --- /dev/null +++ b/swagger-spec/preprints/files_providers_list.yaml @@ -0,0 +1,82 @@ +get: + summary: List storage providers for a preprint + description: >- + Retrieve a list of storage providers for the specified preprint. + Only "osfstorage" is supported for preprints. + + #### Permissions + - Public storage providers are accessible to unauthenticated users. + - Viewing non-public preprints requires appropriate permissions. + + tags: + - Preprints + - Files + + operationId: preprint_storage_providers_list + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint. + + responses: + '200': + description: Successful retrieval of storage providers. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + - links + properties: + id: + type: string + description: The name of the storage provider. + example: osfstorage + type: + type: string + example: storage-providers + attributes: + type: object + properties: + name: + type: string + description: The name of the storage provider. + example: osfstorage + default: + type: boolean + description: Whether this provider is the default. + example: true + links: + type: object + properties: + upload: + type: string + description: Upload URL for this storage provider. + files: + type: string + description: Link to files within this storage provider. + example: + data: + - id: osfstorage + type: storage-providers + attributes: + name: osfstorage + default: true + links: + upload: https://files.osf.io/v1/resources/abc12/providers/osfstorage/ + files: https://api.osf.io/v2/preprints/abc12/files/osfstorage/ + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view storage providers for this preprint. + '404': + description: Not Found. No preprint matches the given ID. \ No newline at end of file diff --git a/swagger-spec/preprints/identifiers_list.yaml b/swagger-spec/preprints/identifiers_list.yaml new file mode 100644 index 0000000..cf0d48e --- /dev/null +++ b/swagger-spec/preprints/identifiers_list.yaml @@ -0,0 +1,96 @@ +get: + summary: List identifiers for a preprint + description: >- + Retrieves a list of identifiers associated with the specified preprint. + Identifiers include DOIs, ARKs, and other unique resource locators. + + #### Permissions + - Public identifiers are accessible to unauthenticated users. + - Private preprints require read access to view their identifiers. + + tags: + - Preprints + - Identifiers + + operationId: preprint_identifiers_list + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint. + + responses: + '200': + description: Successful retrieval of preprint identifiers. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + description: The identifier value itself. + example: doi:10.1234/osf.io/abcde + type: + type: string + description: The type of this resource object. + example: identifiers + attributes: + type: object + required: + - category + - value + properties: + category: + type: string + description: The category of the identifier (e.g., DOI, ARK). + example: doi + value: + type: string + description: The identifier value. + example: 10.1234/osf.io/abcde + links: + type: object + description: Links for pagination and resource access. + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if available). + prev: + type: string + description: Link to the previous page of results (if available). + example: + data: + - id: doi:10.1234/osf.io/abcde + type: identifiers + attributes: + category: doi + value: 10.1234/osf.io/abcde + - id: ark:/12345/osf.io/xyz12 + type: identifiers + attributes: + category: ark + value: ark:/12345/osf.io/xyz12 + links: + self: https://api.osf.io/v2/preprints/abc12/identifiers/ + next: null + prev: null + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view identifiers for this preprint. + '404': + description: Not Found. No preprint matches the given ID. diff --git a/swagger-spec/preprints/relationships_node.yaml b/swagger-spec/preprints/relationships_node.yaml new file mode 100644 index 0000000..c08804e --- /dev/null +++ b/swagger-spec/preprints/relationships_node.yaml @@ -0,0 +1,171 @@ +get: + summary: Retrieve the relationship to the supplemental node of the preprint + description: >- + Retrieve a relationship object that points to the supplemental node associated with this preprint. + + #### Permissions + - Public preprints will return their supplemental node if it exists. + - Private preprints require the user to have read access. + + tags: + - Preprints + + operationId: preprint_node_relationship_read + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint. + + responses: + '200': + description: Successful retrieval of the node relationship. + schema: + type: object + properties: + data: + description: >- + Relationship to the supplemental node. Will be `null` if no node is linked. + type: object + required: + - id + - type + properties: + id: + type: string + description: The ID of the related node. + type: + type: string + example: nodes + links: + type: object + properties: + self: + type: string + description: Link to this relationship. + related: + type: string + description: Link to the related node resource. + examples: + application/json: + data: + id: "abc12" + type: nodes + links: + self: "https://api.osf.io/v2/preprints/abc12/relationships/node/" + related: "https://api.osf.io/v2/preprints/abc12/node/" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view the supplemental node. + '404': + description: Not Found. No preprint matches the given ID. + +patch: + summary: Update the relationship to the supplemental node of the preprint + description: >- + Update the supplemental node relationship for the specified preprint. + + #### Permissions + - Must have `write` permissions on both the preprint and the target node. + + tags: + - Preprints + + operationId: preprint_node_relationship_update + + consumes: + - application/json + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint. + - in: body + name: body + required: true + description: The relationship data for the supplemental node. + schema: + type: object + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + example: nodes + id: + type: string + example: abc12 + + responses: + '200': + description: Successfully updated the supplemental node relationship. + schema: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + type: + type: string + example: nodes + links: + type: object + properties: + self: + type: string + related: + type: string + + '400': + description: Bad request. The node ID may be invalid or missing. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to update this relationship. + '404': + description: Not Found. No preprint or node matches the given ID. + +delete: + summary: Remove the supplemental node relationship from the preprint + description: >- + Remove the link between the preprint and its supplemental node. + + #### Permissions + - Must have `write` permissions on the preprint. + + tags: + - Preprints + + operationId: preprint_node_relationship_delete + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint. + + responses: + '204': + description: Successfully removed the supplemental node relationship. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to modify this relationship. + '404': + description: Not Found. No preprint matches the given ID. diff --git a/swagger-spec/preprints/requests_list.yaml b/swagger-spec/preprints/requests_list.yaml new file mode 100644 index 0000000..35c1e92 --- /dev/null +++ b/swagger-spec/preprints/requests_list.yaml @@ -0,0 +1,139 @@ +post: + summary: Create a Preprint Request + description: >- + Create a new request on the specified preprint. + Typically used for withdrawal requests. + + #### Permissions + - Must be an admin contributor on the preprint to create a request. + + tags: + - Preprints + + operationId: preprint_requests_create + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint to create a request for. + + - in: body + name: body + required: true + description: The request object to be created. + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - attributes + properties: + type: + type: string + example: preprint-requests + attributes: + type: object + required: + - request_type + - comment + properties: + request_type: + type: string + example: withdrawal + description: The type of request. Currently only `withdrawal` is supported. + comment: + type: string + description: Comment explaining the reason for the request. + + responses: + '201': + description: Successfully created the preprint request. + schema: + type: object + properties: + data: + type: object + required: + - id + - type + - attributes + - relationships + properties: + id: + type: string + description: The unique identifier for this request. + type: + type: string + example: preprint-requests + attributes: + type: object + required: + - request_type + - machine_state + - comment + - created + - updated + properties: + request_type: + type: string + machine_state: + type: string + comment: + type: string + created: + type: string + format: date-time + updated: + type: string + format: date-time + relationships: + type: object + properties: + creator: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + type: + type: string + description: The user who created the request. + target: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + type: + type: string + description: The preprint targeted by this request. + links: + type: object + properties: + self: + type: string + + '400': + description: Bad request. Invalid input or missing fields. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to create a request. + '404': + description: Not Found. No preprint matches the given ID. diff --git a/swagger-spec/preprints/review_actions_list.yaml b/swagger-spec/preprints/review_actions_list.yaml new file mode 100644 index 0000000..8e1737f --- /dev/null +++ b/swagger-spec/preprints/review_actions_list.yaml @@ -0,0 +1,192 @@ +get: + summary: List Review Actions for a Preprint + description: >- + Retrieve the list of review actions for the specified preprint. + + Review actions track state transitions and comments made during the review process. + + #### Permissions + - Requires `view_actions` permission on the preprint's provider for full visibility. + - Some actions (like moderator comments) may be hidden if the provider has restrictions. + + tags: + - Preprints + + operationId: preprint_review_actions_list + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint whose review actions are being requested. + + responses: + '200': + description: Successful retrieval of review actions. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + - relationships + properties: + id: + type: string + description: The unique identifier of this review action. + type: + type: string + example: review-actions + attributes: + type: object + required: + - trigger + - from_state + - to_state + - date_created + - date_modified + properties: + trigger: + type: string + description: The action that was triggered, e.g., "accept", "reject", "withdraw". + from_state: + type: string + description: The workflow state before this action. + to_state: + type: string + description: The workflow state after this action. + comment: + type: string + description: The comment added by the user performing the action. + date_created: + type: string + format: date-time + description: The date the action was created. + date_modified: + type: string + format: date-time + description: The date the action was last modified. + relationships: + type: object + properties: + creator: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + description: The ID of the user who created the action. + type: + type: string + example: users + provider: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + description: The ID of the preprint provider. + type: + type: string + example: preprint_providers + target: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + description: The ID of the target preprint. + type: + type: string + example: preprints + links: + type: object + properties: + self: + type: string + description: API link to the review action resource. + + meta: + type: object + description: Pagination or additional metadata. + + examples: + application/json: + data: + - id: "rwa1" + type: review-actions + attributes: + trigger: accept + from_state: pending + to_state: accepted + comment: "Looks good." + date_created: "2023-05-10T14:00:00Z" + date_modified: "2023-05-10T14:00:00Z" + relationships: + creator: + data: + id: "abc123" + type: users + provider: + data: + id: "osf" + type: preprint_providers + target: + data: + id: "abc12" + type: preprints + links: + self: "https://api.osf.io/v2/preprints/abc12/review_actions/rwa1/" + + - id: "rwa2" + type: review-actions + attributes: + trigger: reject + from_state: pending + to_state: rejected + comment: "Needs more revisions." + date_created: "2023-06-15T10:30:00Z" + date_modified: "2023-06-15T10:30:00Z" + relationships: + creator: + data: + id: "mod456" + type: users + provider: + data: + id: "osf" + type: preprint_providers + target: + data: + id: "abc12" + type: preprints + links: + self: "https://api.osf.io/v2/preprints/abc12/review_actions/rwa2/" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view these review actions. + '404': + description: Not Found. No preprint matches the given ID. diff --git a/swagger-spec/preprints/subjects_list.yaml b/swagger-spec/preprints/subjects_list.yaml new file mode 100644 index 0000000..9b063d8 --- /dev/null +++ b/swagger-spec/preprints/subjects_list.yaml @@ -0,0 +1,115 @@ +get: + summary: List Preprint Subjects + description: >- + Retrieve the list of subjects (taxonomy terms) associated with a specific preprint. + + #### Permissions + - Preprint subjects are publicly accessible for published preprints. + - For unpublished preprints, you must have permission to view the preprint. + + tags: + - Preprints + + operationId: preprint_subjects_list + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint whose subjects are being requested. + + responses: + '200': + description: Successful retrieval of preprint subjects. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + description: The unique identifier of the subject. + type: + type: string + example: subjects + attributes: + type: object + properties: + text: + type: string + description: The name of the subject. + parent: + type: string + description: The parent subject ID, if applicable. + relationships: + type: object + properties: + children: + type: object + description: Relationship to any child subjects. + properties: + data: + type: array + items: + type: object + required: + - id + - type + properties: + id: + type: string + description: The unique identifier of the child subject. + type: + type: string + example: subjects + links: + type: object + properties: + self: + type: string + description: Link to the subject resource. + + meta: + type: object + description: Pagination or additional metadata. + + examples: + application/json: + data: + - id: "123" + type: subjects + attributes: + text: "Cognitive Psychology" + parent: "45" + relationships: + children: + data: + - id: "124" + type: subjects + links: + self: "https://api.osf.io/v2/preprints/abc12/subjects/123/" + - id: "124" + type: subjects + attributes: + text: "Developmental Psychology" + parent: "123" + relationships: + children: + data: [] + links: + self: "https://api.osf.io/v2/preprints/abc12/subjects/124/" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view these subjects. + '404': + description: Not Found. No preprint matches the given ID. diff --git a/swagger-spec/preprints/versions_list.yaml b/swagger-spec/preprints/versions_list.yaml new file mode 100644 index 0000000..f3f458f --- /dev/null +++ b/swagger-spec/preprints/versions_list.yaml @@ -0,0 +1,156 @@ +get: + summary: List Preprint Versions + description: >- + Retrieve a list of versions for the specified preprint. + + #### Permissions + - Public versions are accessible to unauthenticated users. + - To view non-public versions, you must have appropriate permissions. + + tags: + - Preprints + + operationId: preprint_versions_list + + parameters: + - name: preprint_id + in: path + required: true + type: string + description: The unique identifier of the preprint whose versions are being requested. + + responses: + '200': + description: Successful retrieval of preprint versions. + schema: + type: object + properties: + data: + type: array + items: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + description: The unique identifier for this preprint version. + type: + type: string + example: preprints + attributes: + type: object + required: + - version + - date_created + - machine_state + properties: + version: + type: integer + description: Version number of this preprint. + date_created: + type: string + format: date-time + description: Date this version was created. + date_published: + type: string + format: date-time + description: Date this version was published, if applicable. + is_published: + type: boolean + description: Whether this version has been published. + machine_state: + type: string + description: Workflow state of the preprint version. + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + description: The ID of the preprint provider. + type: + type: string + example: preprint_providers + primary_file: + type: object + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + description: The ID of the primary file for this version. + type: + type: string + example: files + links: + type: object + properties: + self: + type: string + description: API link to this version. + meta: + type: object + description: Pagination or additional metadata. + + examples: + application/json: + data: + - id: "abc12_v1" + type: preprints + attributes: + version: 1 + date_created: "2023-05-15T12:00:00Z" + date_published: "2023-05-16T12:00:00Z" + is_published: true + machine_state: accepted + relationships: + provider: + data: + type: preprint_providers + id: osf + primary_file: + data: + type: files + id: xyz987 + links: + self: "https://api.osf.io/v2/preprints/abc12_v1/" + - id: "abc12_v2" + type: preprints + attributes: + version: 2 + date_created: "2024-01-10T09:30:00Z" + date_published: null + is_published: false + machine_state: pending + relationships: + provider: + data: + type: preprint_providers + id: osf + primary_file: + data: + type: files + id: xyz988 + links: + self: "https://api.osf.io/v2/preprints/abc12_v2/" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view these versions. + '404': + description: Not Found. No preprint matches the given ID. diff --git a/swagger-spec/registrations/actions_list.yaml b/swagger-spec/registrations/actions_list.yaml new file mode 100644 index 0000000..13a992a --- /dev/null +++ b/swagger-spec/registrations/actions_list.yaml @@ -0,0 +1,71 @@ +get: + summary: List Registration Actions + description: >- + Retrieve a list of actions performed on a specific registration. Actions represent state transitions + or moderation events, such as submission, approval, rejection, and withdrawal requests. + + #### Permissions + - Publicly accessible if the registration is public. + - Administrators of the registration always have access. + - Moderators of the associated Registration Provider may have access depending on action type. + + #### Returns + - A JSON object containing a list of `registration actions` returned in a `data` array. + - Each action describes a specific event or state transition applied to the registration. + + tags: + - Registrations + + operationId: registrations_actions_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successful retrieval of registration actions. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + examples: + application/json: + data: + - id: "action_1" + type: "registration_action" + attributes: + trigger: "submit" + from_state: "initial" + to_state: "unapproved" + comment: "Submitted for review." + date_created: "2024-03-01T12:00:00Z" + date_modified: "2024-03-01T12:00:00Z" + relationships: + creator: + data: + type: "users" + id: "user_1" + target: + data: + type: "registrations" + id: "reg_abc123" + links: + self: "https://api.osf.io/v2/registrations/abc123/actions/action_1/" + meta: + version: "2.0" + + '401': + description: Unauthorized. Authentication credentials were not provided or are invalid. + + '403': + description: Forbidden. You do not have permission to view registration actions for this registration. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/bibliographic_contributors_list.yaml b/swagger-spec/registrations/bibliographic_contributors_list.yaml new file mode 100644 index 0000000..9eadc03 --- /dev/null +++ b/swagger-spec/registrations/bibliographic_contributors_list.yaml @@ -0,0 +1,156 @@ +get: + summary: List Bibliographic Contributors for a Registration + description: >- + Retrieve a list of bibliographic contributors associated with a specific registration. + + Bibliographic contributors are users who have made significant contributions to the registration and are listed as authors. + These contributors appear in citations and are considered authors on the registration's public pages and metadata. + + #### Permissions + - Public registrations expose bibliographic contributors publicly. + - Private registrations require appropriate read permissions to view bibliographic contributors. + + #### Returns + - A JSON object with a `data` array containing contributor resources that are marked as bibliographic for the registration. + + tags: + - Registration + + operationId: registration_bibliographic_contributors_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successful retrieval of bibliographic contributors for the specified registration. + schema: + type: object + properties: + data: + type: array + description: List of bibliographic contributors. + items: + type: object + properties: + id: + type: string + description: Unique identifier of the contributor. + example: "abc123" + type: + type: string + description: Resource type identifier. + example: "contributors" + attributes: + type: object + properties: + bibliographic: + type: boolean + description: Indicates whether this contributor is bibliographic. + example: true + permission: + type: string + description: Contributor's permission level on the registration. + example: "admin" + unregistered_contributor: + type: string + description: Name of the unregistered contributor (if applicable). + example: "John Doe" + index: + type: integer + description: Contributor's order in the contributor list. + example: 0 + relationships: + type: object + properties: + users: + description: The user associated with this contributor (if registered). + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "abc123" + type: + type: string + example: "users" + links: + type: object + properties: + self: + type: string + description: Canonical link to this contributor. + example: "https://api.osf.io/v2/registrations/abcd1/contributors/abc123/" + + links: + type: object + description: Pagination links for the result set. + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/bibliographic_contributors/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/bibliographic_contributors/?page=1" + last: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/bibliographic_contributors/?page=1" + + meta: + type: object + description: Meta information about the response. + properties: + total: + type: integer + description: Total number of bibliographic contributors. + example: 2 + per_page: + type: integer + description: Number of results per page. + example: 10 + + examples: + application/json: + data: + - id: "abc123" + type: "contributors" + attributes: + bibliographic: true + permission: "admin" + unregistered_contributor: null + index: 0 + relationships: + users: + data: + id: "abc123" + type: "users" + links: + self: "https://api.osf.io/v2/registrations/abcd1/contributors/abc123/" + links: + self: "https://api.osf.io/v2/registrations/abcd1/bibliographic_contributors/" + next: null + prev: null + first: "https://api.osf.io/v2/registrations/abcd1/bibliographic_contributors/?page=1" + last: "https://api.osf.io/v2/registrations/abcd1/bibliographic_contributors/?page=1" + meta: + total: 2 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view contributors on this registration. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/cedar_metadata_records_list.yaml b/swagger-spec/registrations/cedar_metadata_records_list.yaml new file mode 100644 index 0000000..e7de47b --- /dev/null +++ b/swagger-spec/registrations/cedar_metadata_records_list.yaml @@ -0,0 +1,163 @@ +get: + summary: List CEDAR Metadata Records for a Registration + description: >- + Retrieve a list of CEDAR metadata records associated with a specific registration. + + CEDAR metadata records store structured metadata collected from external CEDAR templates and are attached to registrations. + Each record corresponds to a specific metadata schema provided by the CEDAR system and enhances the discoverability and documentation of a registration. + + #### Permissions + - Public registrations expose their CEDAR metadata records publicly. + - Private registrations require appropriate read permissions to view CEDAR metadata records. + + #### Returns + - A JSON object with a `data` array containing CEDAR metadata records related to the registration. + + tags: + - Registration + + operationId: registration_cedar_metadata_records_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successful retrieval of CEDAR metadata records for the specified registration. + schema: + type: object + properties: + data: + type: array + description: List of CEDAR metadata records. + items: + type: object + properties: + id: + type: string + description: Unique identifier for the CEDAR metadata record. + example: "cmr789" + type: + type: string + description: Resource type identifier. + example: "cedar-metadata-records" + attributes: + type: object + properties: + title: + type: string + description: Title of the metadata record. + example: "Sample Dataset Metadata" + status: + type: string + description: Status of the metadata record (e.g., draft, submitted, approved). + example: "approved" + schema_name: + type: string + description: Name of the schema used to generate this metadata record. + example: "Human Subjects Research Metadata Schema" + date_created: + type: string + format: date-time + description: ISO 8601 formatted date and time the record was created. + example: "2024-02-20T14:35:00Z" + date_modified: + type: string + format: date-time + description: ISO 8601 formatted date and time the record was last modified. + example: "2024-03-01T10:15:00Z" + relationships: + type: object + properties: + registration: + description: The registration associated with this metadata record. + type: object + properties: + data: + type: object + properties: + id: + type: string + example: "abcd1" + type: + type: string + example: "registrations" + links: + type: object + properties: + self: + type: string + description: Canonical link to this metadata record. + example: "https://api.osf.io/v2/cedar_metadata_records/cmr789/" + + links: + type: object + description: Pagination links for the result set. + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/cedar_metadata_records/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/cedar_metadata_records/?page=1" + last: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/cedar_metadata_records/?page=1" + + meta: + type: object + description: Meta information about the response. + properties: + total: + type: integer + description: Total number of CEDAR metadata records available. + example: 1 + per_page: + type: integer + description: Number of results per page. + example: 10 + + examples: + application/json: + data: + - id: "cmr789" + type: "cedar-metadata-records" + attributes: + title: "Sample Dataset Metadata" + status: "approved" + schema_name: "Human Subjects Research Metadata Schema" + date_created: "2024-02-20T14:35:00Z" + date_modified: "2024-03-01T10:15:00Z" + relationships: + registration: + data: + id: "abcd1" + type: "registrations" + links: + self: "https://api.osf.io/v2/cedar_metadata_records/cmr789/" + links: + self: "https://api.osf.io/v2/registrations/abcd1/cedar_metadata_records/" + next: null + prev: null + first: "https://api.osf.io/v2/registrations/abcd1/cedar_metadata_records/?page=1" + last: "https://api.osf.io/v2/registrations/abcd1/cedar_metadata_records/?page=1" + meta: + total: 1 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view CEDAR metadata records on this registration. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/style_detail.yaml b/swagger-spec/registrations/citation_style_detail.yaml similarity index 100% rename from swagger-spec/registrations/style_detail.yaml rename to swagger-spec/registrations/citation_style_detail.yaml diff --git a/swagger-spec/registrations/style_list.yaml b/swagger-spec/registrations/citation_style_list.yaml similarity index 100% rename from swagger-spec/registrations/style_list.yaml rename to swagger-spec/registrations/citation_style_list.yaml diff --git a/swagger-spec/registrations/implicit_contributors_list.yaml b/swagger-spec/registrations/implicit_contributors_list.yaml new file mode 100644 index 0000000..450fa62 --- /dev/null +++ b/swagger-spec/registrations/implicit_contributors_list.yaml @@ -0,0 +1,143 @@ +get: + summary: List Implicit Contributors for a Registration + description: >- + Retrieve a list of implicit contributors for the specified registration. + + Implicit contributors are users who contributed to a parent node or a fork and whose contributions + are inherited by this registration. They are not explicitly listed as contributors but have an implied relationship. + + #### Permissions + - Public registrations expose their implicit contributors publicly. + - Private registrations require appropriate read permissions to view contributors. + + #### Returns + - A JSON object containing a `data` array of user resources representing implicit contributors to the registration. + + tags: + - Registration + + operationId: registration_implicit_contributors_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + responses: + '200': + description: Successful retrieval of implicit contributors for the specified registration. + schema: + type: object + properties: + data: + type: array + description: List of users who are implicit contributors. + items: + type: object + properties: + id: + type: string + description: The unique identifier of the user. + example: "user123" + type: + type: string + example: "users" + attributes: + type: object + properties: + full_name: + type: string + description: Full name of the user. + example: "Ada Lovelace" + given_name: + type: string + description: Given name of the user. + example: "Ada" + family_name: + type: string + description: Family name of the user. + example: "Lovelace" + date_registered: + type: string + format: date-time + description: Date the user registered on OSF. + example: "2024-01-01T12:00:00Z" + links: + type: object + properties: + self: + type: string + description: Canonical API endpoint for this user. + example: "https://api.osf.io/v2/users/user123/" + + links: + type: object + description: Pagination links for the result set. + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/implicit_contributors/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/implicit_contributors/?page=1" + last: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/implicit_contributors/?page=1" + + meta: + type: object + description: Meta information about the response. + properties: + total: + type: integer + description: Total number of implicit contributors. + example: 2 + per_page: + type: integer + description: Number of results per page. + example: 10 + + examples: + application/json: + data: + - id: "user123" + type: "users" + attributes: + full_name: "Ada Lovelace" + given_name: "Ada" + family_name: "Lovelace" + date_registered: "2024-01-01T12:00:00Z" + links: + self: "https://api.osf.io/v2/users/user123/" + - id: "user456" + type: "users" + attributes: + full_name: "Alan Turing" + given_name: "Alan" + family_name: "Turing" + date_registered: "2023-06-01T08:30:00Z" + links: + self: "https://api.osf.io/v2/users/user456/" + links: + self: "https://api.osf.io/v2/registrations/abcd/implicit_contributors/" + next: null + prev: null + first: "https://api.osf.io/v2/registrations/abcd/implicit_contributors/?page=1" + last: "https://api.osf.io/v2/registrations/abcd/implicit_contributors/?page=1" + meta: + total: 2 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view the implicit contributors. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/linked_by_nodes_list.yaml b/swagger-spec/registrations/linked_by_nodes_list.yaml new file mode 100644 index 0000000..4f0dce6 --- /dev/null +++ b/swagger-spec/registrations/linked_by_nodes_list.yaml @@ -0,0 +1,134 @@ +get: + summary: List Linked By Nodes + description: >- + Retrieve a list of nodes that have added the specified registration as a node link. + + This endpoint allows you to discover which nodes are referencing the given registration by including it in their node links. + + #### Permissions + - Public registrations expose their linked by nodes publicly. + - Private registrations require appropriate read permissions to view this relationship. + + #### Returns + - A JSON object containing a `data` array of node resources that link to the specified registration. + + tags: + - Registration + + operationId: registration_linked_by_nodes_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successful retrieval of nodes linking to the specified registration. + schema: + type: object + properties: + data: + type: array + description: List of nodes that link to the specified registration. + items: + type: object + properties: + id: + type: string + description: The unique identifier of the node. + example: "abcd1" + type: + type: string + example: "nodes" + attributes: + type: object + properties: + title: + type: string + description: The title of the node. + example: "Linked Node Example" + description: + type: string + description: A short description of the node. + example: "This node includes the registration as a node link." + date_created: + type: string + format: date-time + description: Date the node was created. + example: "2024-02-15T12:00:00Z" + public: + type: boolean + description: Whether the node is publicly visible. + example: true + links: + type: object + properties: + self: + type: string + description: The canonical API endpoint for this node. + example: "https://api.osf.io/v2/nodes/abcd1/" + + links: + type: object + description: Pagination links for the result set. + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/linked_by_nodes/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/linked_by_nodes/?page=1" + last: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/linked_by_nodes/?page=1" + + meta: + type: object + description: Meta information about the response. + properties: + total: + type: integer + description: Total number of nodes linking to the specified registration. + example: 3 + per_page: + type: integer + description: Number of results per page. + example: 10 + + examples: + application/json: + data: + - id: "abcd1" + type: "nodes" + attributes: + title: "Linked Node Example" + description: "This node links to the registration." + date_created: "2024-02-15T12:00:00Z" + public: true + links: + self: "https://api.osf.io/v2/nodes/abcd1/" + links: + self: "https://api.osf.io/v2/registrations/fghij/linked_by_nodes/" + next: null + prev: null + first: "https://api.osf.io/v2/registrations/fghij/linked_by_nodes/?page=1" + last: "https://api.osf.io/v2/registrations/fghij/linked_by_nodes/?page=1" + meta: + total: 1 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view linked by nodes. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/linked_by_registrations_list.yaml b/swagger-spec/registrations/linked_by_registrations_list.yaml new file mode 100644 index 0000000..761b93c --- /dev/null +++ b/swagger-spec/registrations/linked_by_registrations_list.yaml @@ -0,0 +1,134 @@ +get: + summary: List Linked By Registrations + description: >- + Retrieve a list of registrations that have added the specified registration as a node link. + + This allows you to discover which registrations are referencing the given registration through their node links. + + #### Permissions + - Public registrations expose their linked by registrations publicly. + - Private registrations require read access to view this relationship. + + #### Returns + - A JSON object containing a `data` array of registration resources that link to this registration. + + tags: + - Registration + + operationId: registration_linked_by_registrations_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successful retrieval of registrations linking to the specified registration. + schema: + type: object + properties: + data: + type: array + description: List of registrations that link to the specified registration. + items: + type: object + properties: + id: + type: string + description: The unique identifier of the registration. + example: "abcde" + type: + type: string + example: "registrations" + attributes: + type: object + properties: + title: + type: string + description: The title of the registration. + example: "My Registration" + description: + type: string + description: Short description of the registration. + example: "This is a test registration." + date_created: + type: string + format: date-time + description: Date the registration was created. + example: "2024-01-01T00:00:00Z" + public: + type: boolean + description: Whether the registration is publicly visible. + example: true + links: + type: object + properties: + self: + type: string + description: The canonical API endpoint for this registration. + example: "https://api.osf.io/v2/registrations/abcde/" + + links: + type: object + description: Pagination links for the result set. + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/linked_by_registrations/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/linked_by_registrations/?page=1" + last: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/linked_by_registrations/?page=1" + + meta: + type: object + description: Meta information about the response. + properties: + total: + type: integer + description: Total number of registrations linking to the specified registration. + example: 1 + per_page: + type: integer + description: Number of results per page. + example: 10 + + examples: + application/json: + data: + - id: "abcde" + type: "registrations" + attributes: + title: "Linked Registration A" + description: "This registration links to the specified registration." + date_created: "2024-01-01T00:00:00Z" + public: true + links: + self: "https://api.osf.io/v2/registrations/abcde/" + links: + self: "https://api.osf.io/v2/registrations/fghij/linked_by_registrations/" + next: null + prev: null + first: "https://api.osf.io/v2/registrations/fghij/linked_by_registrations/?page=1" + last: "https://api.osf.io/v2/registrations/fghij/linked_by_registrations/?page=1" + meta: + total: 1 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to view linked by registrations. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/node_links_detail.yaml b/swagger-spec/registrations/node_links_detail.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/registrations/node_links_list.yaml b/swagger-spec/registrations/node_links_list.yaml new file mode 100644 index 0000000..949ebb1 --- /dev/null +++ b/swagger-spec/registrations/node_links_list.yaml @@ -0,0 +1,137 @@ +get: + summary: List Node Links for a Registration + description: >- + Retrieve a list of node links (linked nodes) associated with a specific registration. + + Node links are references from the registration to other nodes (projects or components). + They allow users to create a relationship between a registration and other nodes within OSF. + + #### Permissions + - Public registrations expose their node links publicly. + - Private registrations require read access to view node links. + + #### Returns + - A JSON object containing a `data` array with node link resources. + + tags: + - Registration + + operationId: registration_node_links_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successful retrieval of node links for the specified registration. + schema: + type: object + properties: + data: + type: array + description: List of node links. + items: + type: object + properties: + id: + type: string + description: The unique identifier for the node link. + example: "abcde" + type: + type: string + example: "node_links" + attributes: + type: object + properties: + title: + type: string + description: The title of the linked node. + example: "Linked Project" + relationships: + type: object + properties: + target: + type: object + description: Link to the target node. + properties: + data: + type: object + properties: + type: + type: string + example: "nodes" + id: + type: string + example: "xyz12" + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/node_links/{node_link_id}/" + + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/node_links/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/node_links/?page=1" + last: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/node_links/?page=1" + + meta: + type: object + properties: + total: + type: integer + example: 1 + description: Total number of node links. + per_page: + type: integer + example: 10 + description: Number of results per page. + + examples: + application/json: + data: + - id: "nl1abc" + type: "node_links" + attributes: + title: "Linked Project A" + relationships: + target: + data: + type: "nodes" + id: "node123" + links: + self: "https://api.osf.io/v2/registrations/fghij/node_links/nl1abc/" + links: + self: "https://api.osf.io/v2/registrations/fghij/node_links/" + next: null + prev: null + first: "https://api.osf.io/v2/registrations/fghij/node_links/?page=1" + last: "https://api.osf.io/v2/registrations/fghij/node_links/?page=1" + meta: + total: 1 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required to access this resource. + '403': + description: Forbidden. You do not have permission to view node links for this registration. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/registrations_list.yaml b/swagger-spec/registrations/registrations_list.yaml new file mode 100644 index 0000000..1554e5f --- /dev/null +++ b/swagger-spec/registrations/registrations_list.yaml @@ -0,0 +1,147 @@ +get: + summary: List Child Registrations of a Registration + description: >- + Retrieve a list of child registrations for a specific registration. + + Registrations can have hierarchical relationships, where one registration can have multiple child registrations. + This endpoint returns all registrations that are children of the given parent registration. + + #### Permissions + - Public registrations will display their children publicly. + - Private registrations require appropriate permissions to view child registrations. + + #### Returns + - A JSON object with a `data` key containing a list of child registration resources. + + tags: + - Registration + + operationId: registrations_children_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the parent registration. + + - in: query + name: page + type: integer + description: Page number of results to view (pagination). + + - in: query + name: filter + type: string + description: Filter results by specific fields, e.g., `filter[title]=keyword`. + + - in: query + name: embed + type: string + description: Comma-separated list of related resources to embed. + + responses: + '200': + description: Successful retrieval of child registrations. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "abcde" + description: The unique identifier of the child registration. + type: + type: string + example: "registrations" + attributes: + type: object + properties: + title: + type: string + example: "My Child Registration" + description: The title of the registration. + description: + type: string + example: "A detailed description of the child registration." + date_created: + type: string + format: date-time + example: "2023-01-01T12:00:00Z" + date_modified: + type: string + format: date-time + example: "2023-01-02T12:00:00Z" + relationships: + type: object + description: Relationships to other resources. + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/abcde/" + description: The canonical API endpoint for this child registration. + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/registrations/" + next: + type: string + example: null + prev: + type: string + example: null + first: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/registrations/?page=1" + last: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/registrations/?page=1" + meta: + type: object + properties: + total: + type: integer + example: 1 + description: Total number of child registrations available. + per_page: + type: integer + example: 10 + description: Number of items returned per page. + + examples: + application/json: + data: + - id: "abcde" + type: "registrations" + attributes: + title: "Child Registration 1" + description: "Description for child registration 1." + date_created: "2023-01-01T12:00:00Z" + date_modified: "2023-01-02T12:00:00Z" + relationships: {} + links: + self: "https://api.osf.io/v2/registrations/abcde/" + links: + self: "https://api.osf.io/v2/registrations/fghij/registrations/" + next: null + prev: null + first: "https://api.osf.io/v2/registrations/fghij/registrations/?page=1" + last: "https://api.osf.io/v2/registrations/fghij/registrations/?page=1" + meta: + total: 1 + per_page: 10 + + '401': + description: Unauthorized. Authentication is required to access this resource. + '403': + description: Forbidden. You do not have permission to access these registrations. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/relationships_institutions_list.yaml b/swagger-spec/registrations/relationships_institutions_list.yaml new file mode 100644 index 0000000..12e5698 --- /dev/null +++ b/swagger-spec/registrations/relationships_institutions_list.yaml @@ -0,0 +1,77 @@ +get: + summary: Retrieve Institution Relationships for a Registration + description: >- + Retrieve the relationship data for the institutions affiliated with a specific registration. + + This endpoint returns a resource identifier object for each institution related to the registration. + To retrieve detailed information about these institutions, use the `related` link or query the `/institutions/` endpoint. + + #### Permissions + - Public registrations will display their institutions publicly. + - Private registrations require appropriate permissions to view affiliated institutions. + + #### Returns + - A JSON object with a `data` key, containing an array of `institutions` resource identifier objects (`id` and `type`). + + tags: + - Registration + + operationId: relationships_institutions_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successfully retrieved the affiliated institutions relationship data for this registration. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "cos" + description: The unique identifier for the institution. + type: + type: string + example: "institutions" + description: The type of the related resource (always `institutions` for this endpoint). + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/relationships/institutions/" + description: The link to this relationship view. + related: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/institutions/" + description: The link to the related institutions collection. + + examples: + application/json: + data: + - id: "cos" + type: "institutions" + - id: "uva" + type: "institutions" + links: + self: "https://api.osf.io/v2/registrations/abcd1/relationships/institutions/" + related: "https://api.osf.io/v2/registrations/abcd1/institutions/" + + '401': + description: Unauthorized. Authentication is required to access this resource. + + '403': + description: Forbidden. You do not have permission to access the institutions of this registration. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/relationships_linked_nodes_list.yaml b/swagger-spec/registrations/relationships_linked_nodes_list.yaml new file mode 100644 index 0000000..ff1f6e9 --- /dev/null +++ b/swagger-spec/registrations/relationships_linked_nodes_list.yaml @@ -0,0 +1,81 @@ +get: + summary: Retrieve Linked Nodes Relationship for a Registration or Node + description: >- + Retrieve the relationship data for linked nodes associated with a specific registration or node. + + Linked nodes are nodes that have been explicitly linked to the current registration/node through the `linked_nodes` relationship. + + This endpoint returns an array of linked node resource identifier objects (`id` and `type`). + To retrieve detailed information about each linked node, you should query the `/linked_nodes/` endpoint + or follow the `related` link provided in this response. + + #### Permissions + - Public nodes/registrations expose linked nodes publicly. + - Private nodes/registrations require appropriate permissions to view their linked nodes. + + #### Returns + - A JSON object with a `data` key, containing an array of `nodes` resource identifier objects (`id` and `type`). + + tags: + - Registration + + operationId: relationships_linked_nodes_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + # Swap with node_id if this is for nodes + + responses: + '200': + description: Successfully retrieved linked nodes relationship data for this registration/node. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "abcde" + description: The unique identifier of the linked node. + type: + type: string + example: "nodes" + description: The type of the related resource (always `nodes` for this endpoint). + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/relationships/linked_nodes/" + description: The link to this relationship view. + related: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/linked_nodes/" + description: The link to the related linked nodes resources. + + examples: + application/json: + data: + - id: "abcde" + type: "nodes" + - id: "fghij" + type: "nodes" + links: + self: "https://api.osf.io/v2/registrations/abcd1/relationships/linked_nodes/" + related: "https://api.osf.io/v2/registrations/abcd1/linked_nodes/" + + '401': + description: Unauthorized. Authentication is required to access this resource. + + '403': + description: Forbidden. You do not have permission to access the linked nodes of this registration. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/relationships_linked_registrations_list.yaml b/swagger-spec/registrations/relationships_linked_registrations_list.yaml new file mode 100644 index 0000000..8fd4843 --- /dev/null +++ b/swagger-spec/registrations/relationships_linked_registrations_list.yaml @@ -0,0 +1,80 @@ +get: + summary: Retrieve Linked Registrations Relationship for a Registration + description: >- + Retrieve the relationship data for linked registrations associated with a specific registration. + + Linked registrations are registrations that have been explicitly linked to the given registration through the `linked_registrations` relationship. + + This endpoint returns an array of linked registration resource identifier objects (`id` and `type`). + To retrieve detailed information about each linked registration, you should query the `/registrations/{registration_id}/linked_registrations/` endpoint + or follow the `related` link provided in this response. + + #### Permissions + - Public registrations expose linked registrations publicly. + - Private registrations require appropriate permissions to view their linked registrations. + + #### Returns + - A JSON object with a `data` key, containing an array of `registration` resource identifier objects (`id` and `type`). + + tags: + - Registration + + operationId: registration_linked_registrations_relationship_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successfully retrieved linked registrations relationship data for this registration. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "reg123" + description: The unique identifier of the linked registration. + type: + type: string + example: "registrations" + description: The type of the related resource (always `registrations` for this endpoint). + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/relationships/linked_registrations/" + description: The link to this relationship view. + related: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/linked_registrations/" + description: The link to the related linked registrations resources. + + examples: + application/json: + data: + - id: "reg123" + type: "registrations" + - id: "reg456" + type: "registrations" + links: + self: "https://api.osf.io/v2/registrations/abcd1/relationships/linked_registrations/" + related: "https://api.osf.io/v2/registrations/abcd1/linked_registrations/" + + '401': + description: Unauthorized. Authentication is required to access this resource. + + '403': + description: Forbidden. You do not have permission to access the linked registrations of this registration. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/relationships_subjects_list.yaml b/swagger-spec/registrations/relationships_subjects_list.yaml new file mode 100644 index 0000000..216778f --- /dev/null +++ b/swagger-spec/registrations/relationships_subjects_list.yaml @@ -0,0 +1,77 @@ +get: + summary: Retrieve Subjects Relationship for a Registration + description: >- + Retrieve the relationship data for the subjects associated with a specific registration. + + This endpoint returns an array of subject identifiers in a `relationships` object, without the full subject resource details. + To get the full details of the subjects, you should follow the `related` link provided in the relationships object or query the `/registrations/{registration_id}/subjects/` endpoint. + + #### Permissions + - Public registrations expose this relationship publicly. + - Private registrations require appropriate permissions to view their subjects. + + #### Returns + - A JSON object with a `data` key, which contains an array of `subject` resource identifier objects (`id` and `type`). + + tags: + - Registration + + operationId: registration_subjects_relationship_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + responses: + '200': + description: Successfully retrieved the subject relationship data for this registration. + schema: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + example: "subj123" + description: The unique identifier of the subject. + type: + type: string + example: "subjects" + description: The type of the related resource (always `subjects` for this endpoint). + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/relationships/subjects/" + description: The link to this relationship view. + related: + type: string + example: "https://api.osf.io/v2/registrations/{registration_id}/subjects/" + description: The link to the related subjects resources. + + examples: + application/json: + data: + - id: "subj123" + type: "subjects" + - id: "subj456" + type: "subjects" + links: + self: "https://api.osf.io/v2/registrations/abcd1/relationships/subjects/" + related: "https://api.osf.io/v2/registrations/abcd1/subjects/" + + '401': + description: Unauthorized. Authentication is required to access this resource. + + '403': + description: Forbidden. You do not have permission to access this registration's subjects. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/requests_list.yaml b/swagger-spec/registrations/requests_list.yaml new file mode 100644 index 0000000..a9b5279 --- /dev/null +++ b/swagger-spec/registrations/requests_list.yaml @@ -0,0 +1,81 @@ +get: + summary: List Requests for a Registration + description: >- + Retrieve a list of requests associated with a specific registration. + + Requests allow contributors and moderators to manage changes to a registration, + including withdrawal requests, embargo requests, and schema update requests. + + #### Permissions + - Public registrations expose some request metadata publicly. + - Private registrations require read access for non-admin contributors. + - Only admins and moderators can view and manage sensitive request details. + + #### Returns + - A JSON object with a `data` key containing an array of request records. + - Each request includes the type of request (withdrawal, embargo, etc.), its state, + and information about who initiated the request. + + tags: + - Registrations + + operationId: registrations_requests_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + - in: query + name: filter[type] + type: string + description: | + Filter requests by type. + Allowed values: + - withdrawal + - embargo + - schema_update + + - in: query + name: page + type: integer + description: Page number of results to return (pagination). + + responses: + '200': + description: Successfully retrieved the list of requests for this registration. + examples: + application/json: + data: + - id: "rq1xyz" + type: "registration_requests" + attributes: + request_type: "withdrawal" + state: "pending" + created: "2024-03-01T12:00:00Z" + updated: "2024-03-03T09:00:00Z" + comment: "Requesting withdrawal due to data errors." + relationships: + creator: + data: + type: "users" + id: "user123" + target: + data: + type: "registrations" + id: "reg456" + links: + self: "https://api.osf.io/v2/registration_requests/rq1xyz/" + meta: + version: "2.0" + + '401': + description: Unauthorized. Authentication is required to access requests for this registration. + + '403': + description: Forbidden. You do not have permission to view requests for this registration. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/resources_list.yaml b/swagger-spec/registrations/resources_list.yaml new file mode 100644 index 0000000..d1eb256 --- /dev/null +++ b/swagger-spec/registrations/resources_list.yaml @@ -0,0 +1,70 @@ +get: + summary: List Related Resources for a Registration + description: >- + Retrieve a list of resources associated with a specific registration. + + This endpoint returns a list of nodes, preprints, and other resources that have been explicitly linked to the registration as related resources. + These resources help provide additional context, background, or supporting materials for the registration. + + #### Permissions + - Public registrations expose their related resources publicly. + - Private registrations require the user to have read access to view related resources. + + #### Returns + - A JSON object with a `data` key containing an array of related resources. + - Related resources may include nodes, preprints, and other OSF resources. + + tags: + - Registrations + - Resources + + operationId: registrations_resources_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + - in: query + name: page + type: integer + description: Page number of results to return (pagination). + + responses: + '200': + description: Successfully retrieved related resources for this registration. + examples: + application/json: + data: + - id: "xyz123" + type: "nodes" + attributes: + title: "Supporting Project A" + description: "Dataset related to the registration study" + public: true + date_created: "2024-01-10T10:00:00Z" + date_modified: "2024-03-22T15:30:00Z" + relationships: + contributors: + links: + related: + href: "https://api.osf.io/v2/nodes/xyz123/contributors/" + affiliated_institutions: + links: + related: + href: "https://api.osf.io/v2/nodes/xyz123/institutions/" + links: + self: "https://api.osf.io/v2/nodes/xyz123/" + meta: + version: "2.0" + + '401': + description: Unauthorized. Authentication is required to access related resources for this registration. + + '403': + description: Forbidden. You do not have permission to view the related resources for this registration. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/schema_responses_list.yaml b/swagger-spec/registrations/schema_responses_list.yaml new file mode 100644 index 0000000..3352346 --- /dev/null +++ b/swagger-spec/registrations/schema_responses_list.yaml @@ -0,0 +1,86 @@ +get: + summary: List Schema Responses for a Registration + description: >- + Retrieve a list of all Schema Responses associated with a specific registration. + + Schema Responses represent the answers provided to a registration schema's questions. They reflect the current and historical state of responses submitted for the registration. + + A registration can have multiple schema responses over time due to edits or updates, depending on the registration provider's workflow. + + #### Permissions + - Publicly accessible for public registrations. + - Private registrations require appropriate permissions (must be a contributor with read access). + + #### Returns + - A JSON object with a `data` key containing an array of schema response resources. + - Each schema response includes its current state, related actions, and the data provided in the registration form. + + tags: + - Registrations + + operationId: registrations_schema_responses_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + - in: query + name: page + type: integer + description: Page number of results to view (pagination). + + - in: query + name: filter[state] + type: string + description: Filter schema responses by their state (e.g., `in_progress`, `unapproved`, `approved`, `pending_moderation`). + + responses: + '200': + description: Successfully retrieved list of schema responses for this registration. + schema: + type: object + properties: + data: + type: array + items: + $ref: '../schema_responses/definition.yaml' + examples: + application/json: + data: + - id: "sr123" + type: "schema-responses" + attributes: + state: "approved" + date_created: "2024-05-01T12:00:00Z" + date_modified: "2024-06-10T09:30:00Z" + revision_justification: "Updated methodology section for clarity" + relationships: + registration_schema: + data: + type: "registration-schemas" + id: "rs1" + registration: + data: + type: "registrations" + id: "abcd1" + current_user_permissions: + data: + - "read" + - "write" + - "admin" + links: + self: "https://api.osf.io/v2/schema_responses/sr123/" + meta: + version: "2.0" + + '401': + description: Unauthorized. Authentication is required to access schema responses for a private registration. + + '403': + description: Forbidden. You do not have permission to view schema responses for this registration. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registrations/subjects_list.yaml b/swagger-spec/registrations/subjects_list.yaml new file mode 100644 index 0000000..01623d9 --- /dev/null +++ b/swagger-spec/registrations/subjects_list.yaml @@ -0,0 +1,80 @@ +get: + summary: List Registration Subjects + description: >- + Retrieve a list of taxonomy subjects assigned to a specific registration. + + Subjects represent the topics, disciplines, or areas of research that the registration is categorized under. + These subjects help with search, discovery, and classification within the OSF platform. + + #### Permissions + - Publicly accessible if the registration is public. + - Private registrations require admin permissions to access. + + #### Returns + - A JSON object with a `data` key containing an array of subject resources. + - Each subject describes a taxonomy term, including its name and hierarchical position. + + tags: + - Registrations + + operationId: registrations_subjects_list + + parameters: + - in: path + name: registration_id + type: string + required: true + description: The unique identifier of the registration. + + - in: query + name: page + type: integer + description: Page number of results to view (pagination). + + - in: query + name: filter[text] + type: string + description: Filter subjects by name. + + responses: + '200': + description: Successfully retrieved list of subjects for this registration. + schema: + type: object + properties: + data: + type: array + items: + $ref: '../taxonomies/definition.yaml' + examples: + application/json: + data: + - id: "1234" + type: "taxonomy" + attributes: + text: "Psychology" + parent_ids: [] + child_ids: + - "5678" + path: ["Psychology"] + is_highlighted: true + relationships: + parent: + data: null + children: + data: + - type: "taxonomy" + id: "5678" + links: + self: "https://api.osf.io/v2/taxonomies/1234/" + meta: + version: "2.0" + + '401': + description: Unauthorized. Authentication is required to access subjects for a private registration. + + '403': + description: Forbidden. You do not have permission to view subjects for this registration. + + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/requests/actions_list.yaml b/swagger-spec/requests/actions_list.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/requests/definition.yaml b/swagger-spec/requests/definition.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/requests/detail.yaml b/swagger-spec/requests/detail.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/resources/definition.yaml b/swagger-spec/resources/definition.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/resources/detail.yaml b/swagger-spec/resources/detail.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/resources/list.yaml b/swagger-spec/resources/list.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index f0c1deb..042810c 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -1135,6 +1135,37 @@ paths: /nodes/{node_id}/wikis/: $ref: 'nodes/wikis_list.yaml' + /nodes/{node_id}/linked_by_nodes/: + $ref: 'nodes/linked_by_nodes_list.yaml' + + /nodes/{node_id}/linked_by_registrations/: + $ref: 'nodes/linked_by_registrations_list.yaml' + + /nodes/{node_id}/relationships/institutions/: + $ref: 'nodes/relationships_institutions_list.yaml' + + /nodes/{node_id}/relationships/linked_nodes/: + $ref: 'nodes/relationships_linked_nodes_list.yaml' + + /nodes/{node_id}/relationships/linked_registrations/: + $ref: 'nodes/relationships_linked_registrations_list.yaml' + + /nodes/{node_id}/relationships/subjects/: + $ref: 'nodes/relationships_subjects_list.yaml' + + /nodes/{node_id}/requests/: + $ref: 'nodes/requests_list.yaml' + + /nodes/{node_id}/settings/: + $ref: 'nodes/node_settings_list.yaml' + + /nodes/{node_id}/storage/: + $ref: 'nodes/node_storage_list.yaml' + + /nodes/{node_id}/subjects/: + $ref: 'nodes/subjects_list.yaml' + + ################# # PREPRINTS # @@ -1167,6 +1198,29 @@ paths: /preprints/{preprint_id}/relationships/institutions/: $ref: 'preprints/institutions_relationship_list.yaml' + /preprints/{preprint_id}/files/: + $ref: 'preprints/files_providers_list.yaml' + + /preprints/{preprint_id}/files/osfstorage/: + $ref: 'preprints/files_osfstorage_list.yaml' + + /preprints/{preprint_id}/identifiers/: + $ref: 'preprints/identifiers_list.yaml' + + /preprints/{preprint_id}/relationships/node/: + $ref: 'preprints/relationships_node.yaml' + + /preprints/{preprint_id}/requests/: + $ref: 'preprints/requests_list.yaml' + + /preprints/{preprint_id}/review_actions/: + $ref: 'preprints/review_actions_list.yaml' + + /preprints/{preprint_id}/subjects/: + $ref: 'preprints/subjects_list.yaml' + + /preprints/{preprint_id}/versions/: + $ref: 'preprints/versions_list.yaml' ########################## @@ -1199,10 +1253,10 @@ paths: $ref: 'registrations/detail.yaml' /registrations/{registration_id}/citations/: - $ref: 'registrations/style_list.yaml' + $ref: 'registrations/citation_style_list.yaml' /registrations/{registration_id}/citations/{citation_id}/: - $ref: 'registrations/style_detail.yaml' + $ref: 'registrations/citation_style_detail.yaml' /registrations/{registration_id}/children/: $ref: 'registrations/children_list.yaml' @@ -1240,6 +1294,60 @@ paths: /registrations/{registration_id}/logs/: $ref: 'registrations/logs_list.yaml' + /registrations/{registration_id}/actions/: + $ref: 'registrations/actions_list.yaml' + + /registrations/{registration_id}/bibliographic_contributors/: + $ref: 'registrations/bibliographic_contributors_list.yaml' + + /registrations/{registration_id}/cedar_metadata_records/: + $ref: 'registrations/cedar_metadata_records_list.yaml' + + /registrations/{registration_id}/citation/: + $ref: 'registrations/citation_style_list.yaml' + + /registrations/{registration_id}/citation/{citation_id}/: + $ref: 'registrations/citation_style_detail.yaml' + + /registrations/{registration_id}/implicit_contributors/: + $ref: 'registrations/implicit_contributors_list.yaml' + + /registrations/{registration_id}/linked_by_nodes/: + $ref: 'registrations/linked_by_nodes_list.yaml' + + /registrations/{registration_id}/linked_by_registrations/: + $ref: 'registrations/linked_by_registrations_list.yaml' + + /registrations/{registration_id}/node_links/: + $ref: 'registrations/node_links_list.yaml' + + /registrations/{registration_id}/registrations/: + $ref: 'registrations/registrations_list.yaml' + + /registrations/{registration_id}/relationships/institutions/: + $ref: 'registrations/relationships_institutions_list.yaml' + + /registrations/{registration_id}/relationships/linked_nodes/: + $ref: 'registrations/relationships_linked_nodes_list.yaml' + + /registrations/{registration_id}/relationships/linked_registrations/: + $ref: 'registrations/relationships_linked_registrations_list.yaml' + + /registrations/{registration_id}/relationships/subjects/: + $ref: 'registrations/relationships_subjects_list.yaml' + + /registrations/{registration_id}/requests/: + $ref: 'registrations/requests_list.yaml' + + /registrations/{registration_id}/resources/: + $ref: 'registrations/resources_list.yaml' + + /registrations/{registration_id}/schema_responses/: + $ref: 'registrations/schema_responses_list.yaml' + + /registrations/{registration_id}/subjects/: + $ref: 'registrations/subjects_list.yaml' + /registrations/{registration_id}/view_only_links/: $ref: 'registrations/view_only_links_list.yaml' From 181961121cd359079bf9781da7c313bc142cf523 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Tue, 18 Mar 2025 16:11:31 -0400 Subject: [PATCH 11/21] add provider routes --- .../definition.yaml | 0 .../detail.yaml | 4 +- .../licenses.yaml | 2 +- .../list.yaml | 0 .../moderators_detail.yaml | 4 +- .../moderators_list.yaml | 4 +- .../provider_moderator_detail.yaml | 47 ++++ .../provider_moderator_list.yaml | 46 ++++ ...provider_taxonomies_highlitghted_list.yaml | 43 ++++ .../provider_taxonomies_list.yaml | 48 ++++ .../subjects.yaml | 4 +- .../subjects_highlighted_list.yaml} | 4 +- .../submissions.yaml | 4 +- .../taxonomies_highlighted_list.yaml | 100 ++++++++ .../collection_providers/taxonomies_list.yaml | 87 +++++++ swagger-spec/preprint_providers/detail.yaml | 2 +- .../preprint_providers/licenses_list.yaml | 2 +- .../preprint_providers/moderators_detail.yaml | 62 +++++ .../preprint_providers/moderators_list.yaml | 183 ++++++++++++++ .../preprint_providers/preprints_list.yaml | 2 +- .../provider_moderator_detail.yaml | 215 ++++++++++++++++ .../provider_moderator_list.yaml | 239 ++++++++++++++++++ .../provider_subjects_highlighted_list.yaml | 69 +++++ .../provider_subjects_list.yaml | 104 ++++++++ .../provider_taxonomies_highlighted_list.yaml | 88 +++++++ .../provider_taxonomies_list.yaml | 88 +++++++ .../providers_citation_styles.yaml | 105 ++++++++ .../subjects_highlighted_list.yaml | 0 ...axonomies_list.yaml => subjects_list.yaml} | 2 +- .../preprint_providers/withdraw_requests.yaml | 115 +++++++++ swagger-spec/preprints/definition.yaml | 2 +- .../moderators_detail.yaml | 105 ++++++++ .../moderators_list.yaml | 73 ++++++ ...provider_taxonomies_highlitghted_list.yaml | 25 ++ .../provider_taxonomies_list.yaml | 30 +++ .../registration_actions_list.yaml | 122 +++++++++ .../registration_requests_list.yaml | 110 ++++++++ .../registrations_list.yaml | 108 ++++++++ .../registrations_schema_list.yaml | 132 ++++++++++ .../registrations_subjects_list.yaml | 126 +++++++++ .../registrations_submissions_list.yaml | 138 ++++++++++ .../subjects_highlighted_list.yaml | 25 ++ swagger-spec/swagger.yaml | 105 ++++++-- 43 files changed, 2731 insertions(+), 43 deletions(-) rename swagger-spec/{collection_provider => collection_providers}/definition.yaml (100%) rename swagger-spec/{collection_provider => collection_providers}/detail.yaml (98%) rename swagger-spec/{collection_provider => collection_providers}/licenses.yaml (99%) rename swagger-spec/{collection_provider => collection_providers}/list.yaml (100%) rename swagger-spec/{collection_provider => collection_providers}/moderators_detail.yaml (97%) rename swagger-spec/{collection_provider => collection_providers}/moderators_list.yaml (98%) create mode 100644 swagger-spec/collection_providers/provider_moderator_detail.yaml create mode 100644 swagger-spec/collection_providers/provider_moderator_list.yaml create mode 100644 swagger-spec/collection_providers/provider_taxonomies_highlitghted_list.yaml create mode 100644 swagger-spec/collection_providers/provider_taxonomies_list.yaml rename swagger-spec/{collection_provider => collection_providers}/subjects.yaml (98%) rename swagger-spec/{collection_provider/subjects_highlighted.yaml => collection_providers/subjects_highlighted_list.yaml} (96%) rename swagger-spec/{collection_provider => collection_providers}/submissions.yaml (99%) create mode 100644 swagger-spec/collection_providers/taxonomies_highlighted_list.yaml create mode 100644 swagger-spec/collection_providers/taxonomies_list.yaml create mode 100644 swagger-spec/preprint_providers/moderators_detail.yaml create mode 100644 swagger-spec/preprint_providers/moderators_list.yaml create mode 100644 swagger-spec/preprint_providers/provider_moderator_detail.yaml create mode 100644 swagger-spec/preprint_providers/provider_moderator_list.yaml create mode 100644 swagger-spec/preprint_providers/provider_subjects_highlighted_list.yaml create mode 100644 swagger-spec/preprint_providers/provider_subjects_list.yaml create mode 100644 swagger-spec/preprint_providers/provider_taxonomies_highlighted_list.yaml create mode 100644 swagger-spec/preprint_providers/provider_taxonomies_list.yaml create mode 100644 swagger-spec/preprint_providers/providers_citation_styles.yaml create mode 100644 swagger-spec/preprint_providers/subjects_highlighted_list.yaml rename swagger-spec/preprint_providers/{taxonomies_list.yaml => subjects_list.yaml} (98%) create mode 100644 swagger-spec/preprint_providers/withdraw_requests.yaml create mode 100644 swagger-spec/registration_providers/moderators_detail.yaml create mode 100644 swagger-spec/registration_providers/moderators_list.yaml create mode 100644 swagger-spec/registration_providers/provider_taxonomies_highlitghted_list.yaml create mode 100644 swagger-spec/registration_providers/provider_taxonomies_list.yaml create mode 100644 swagger-spec/registration_providers/registration_actions_list.yaml create mode 100644 swagger-spec/registration_providers/registration_requests_list.yaml create mode 100644 swagger-spec/registration_providers/registrations_list.yaml create mode 100644 swagger-spec/registration_providers/registrations_schema_list.yaml create mode 100644 swagger-spec/registration_providers/registrations_subjects_list.yaml create mode 100644 swagger-spec/registration_providers/registrations_submissions_list.yaml create mode 100644 swagger-spec/registration_providers/subjects_highlighted_list.yaml diff --git a/swagger-spec/collection_provider/definition.yaml b/swagger-spec/collection_providers/definition.yaml similarity index 100% rename from swagger-spec/collection_provider/definition.yaml rename to swagger-spec/collection_providers/definition.yaml diff --git a/swagger-spec/collection_provider/detail.yaml b/swagger-spec/collection_providers/detail.yaml similarity index 98% rename from swagger-spec/collection_provider/detail.yaml rename to swagger-spec/collection_providers/detail.yaml index 5fb0f6e..e028d71 100644 --- a/swagger-spec/collection_provider/detail.yaml +++ b/swagger-spec/collection_providers/detail.yaml @@ -1,4 +1,4 @@ -# /provider/collections/{collection_id}/ +# /provider/collections/{provider_id}/ get: summary: Collections Providers Detail description: >- @@ -18,7 +18,7 @@ get: - in: path type: string required: true - name: collection_id + name: provider_id description: 'A short id for that collection' tags: - Collection Providers diff --git a/swagger-spec/collection_provider/licenses.yaml b/swagger-spec/collection_providers/licenses.yaml similarity index 99% rename from swagger-spec/collection_provider/licenses.yaml rename to swagger-spec/collection_providers/licenses.yaml index a0da22f..552377c 100644 --- a/swagger-spec/collection_provider/licenses.yaml +++ b/swagger-spec/collection_providers/licenses.yaml @@ -20,7 +20,7 @@ get: - in: path type: string required: true - name: collection_id + name: provider_id description: 'A short id for that collection' tags: - Collection Providers diff --git a/swagger-spec/collection_provider/list.yaml b/swagger-spec/collection_providers/list.yaml similarity index 100% rename from swagger-spec/collection_provider/list.yaml rename to swagger-spec/collection_providers/list.yaml diff --git a/swagger-spec/collection_provider/moderators_detail.yaml b/swagger-spec/collection_providers/moderators_detail.yaml similarity index 97% rename from swagger-spec/collection_provider/moderators_detail.yaml rename to swagger-spec/collection_providers/moderators_detail.yaml index ef93219..47aaee2 100644 --- a/swagger-spec/collection_provider/moderators_detail.yaml +++ b/swagger-spec/collection_providers/moderators_detail.yaml @@ -1,4 +1,4 @@ -# /provider/collections/{collection_id}/moderators/{moderator_id}/: +# /provider/collections/{provider_id}/moderators/{moderator_id}/: get: summary: Collections Providers Moderators Detail description: >- @@ -18,7 +18,7 @@ get: - in: path type: string required: true - name: collection_id + name: provider_id description: 'A short id for that collection' - in: path type: string diff --git a/swagger-spec/collection_provider/moderators_list.yaml b/swagger-spec/collection_providers/moderators_list.yaml similarity index 98% rename from swagger-spec/collection_provider/moderators_list.yaml rename to swagger-spec/collection_providers/moderators_list.yaml index 0c92723..ed28121 100644 --- a/swagger-spec/collection_provider/moderators_list.yaml +++ b/swagger-spec/collection_providers/moderators_list.yaml @@ -1,4 +1,4 @@ -# /provider/collections/{collection_id}/moderators/: +# /provider/collections/{provider_id}/moderators/: get: summary: Collections Providers Moderators List description: >- @@ -20,7 +20,7 @@ get: - in: path type: string required: true - name: collection_id + name: provider_id description: 'A short id for that collection' tags: - Collection Providers diff --git a/swagger-spec/collection_providers/provider_moderator_detail.yaml b/swagger-spec/collection_providers/provider_moderator_detail.yaml new file mode 100644 index 0000000..7333919 --- /dev/null +++ b/swagger-spec/collection_providers/provider_moderator_detail.yaml @@ -0,0 +1,47 @@ +get: + operationId: collection_provider_moderators_detail + summary: Retrieve a Moderator for a Collection Provider + description: | + Retrieve details about a specific moderator assigned to a Collection Provider. + + parameters: + - in: path + name: provider_id + required: true + schema: + type: string + description: The unique ID of the collection provider. + + - in: path + name: moderator_id + required: true + schema: + type: string + description: The unique ID of the moderator (user ID). + + tags: + - Collection Providers + + responses: + '200': + description: Moderator details retrieved successfully. + content: + application/vnd.api+json: + example: + data: + id: "abc123" + type: "users" + attributes: + full_name: "Moderator One" + permission_group: "moderator" + + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view this moderator. + '404': + description: Moderator or collection provider not found. + + security: + - CookieAuth: [] + diff --git a/swagger-spec/collection_providers/provider_moderator_list.yaml b/swagger-spec/collection_providers/provider_moderator_list.yaml new file mode 100644 index 0000000..1c920a7 --- /dev/null +++ b/swagger-spec/collection_providers/provider_moderator_list.yaml @@ -0,0 +1,46 @@ + +get: + operationId: collection_provider_moderators_list + summary: List Moderators for a Collection Provider + description: | + Retrieve a list of moderators assigned to a specific Collection Provider. + Moderators can review and manage submissions under the provider. + + parameters: + - in: path + name: provider_id + required: true + schema: + type: string + description: The unique ID of the collection provider. + + tags: + - Collection Providers + + responses: + '200': + description: A list of moderators for the specified collection provider. + content: + application/vnd.api+json: + example: + data: + - id: "abc123" + type: "users" + attributes: + full_name: "Moderator One" + permission_group: "moderator" + - id: "def456" + type: "users" + attributes: + full_name: "Admin User" + permission_group: "admin" + + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view moderators for this provider. + '404': + description: Collection provider not found. + + security: + - CookieAuth: [] diff --git a/swagger-spec/collection_providers/provider_taxonomies_highlitghted_list.yaml b/swagger-spec/collection_providers/provider_taxonomies_highlitghted_list.yaml new file mode 100644 index 0000000..988f4ee --- /dev/null +++ b/swagger-spec/collection_providers/provider_taxonomies_highlitghted_list.yaml @@ -0,0 +1,43 @@ +get: + operationId: collection_provider_taxonomies_highlighted_list + summary: List Highlighted Taxonomies for a Collection Provider (Deprecated) + description: | + Retrieve the list of highlighted taxonomies for a Collection Provider. + + **Deprecated:** Use the `highlighted subjects` endpoint instead. + + deprecated: true + + parameters: + - in: path + name: provider_id + required: true + schema: + type: string + description: The unique ID of the collection provider. + + tags: + - Collection Providers + + responses: + '200': + description: A list of highlighted taxonomies. + content: + application/vnd.api+json: + example: + data: + - id: "xyz-highlighted" + type: "taxonomies" + attributes: + text: "Open Science" + parents: [] + + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view taxonomies for this provider. + '404': + description: Collection provider not found. + + security: + - CookieAuth: [] diff --git a/swagger-spec/collection_providers/provider_taxonomies_list.yaml b/swagger-spec/collection_providers/provider_taxonomies_list.yaml new file mode 100644 index 0000000..f9ae302 --- /dev/null +++ b/swagger-spec/collection_providers/provider_taxonomies_list.yaml @@ -0,0 +1,48 @@ +get: + operationId: collection_provider_taxonomies_list + summary: List Taxonomies for a Collection Provider (Deprecated) + description: | + Retrieve the full taxonomy for a specific Collection Provider. + + **Deprecated:** Use `subjects` endpoints instead. + + deprecated: true + + parameters: + - in: path + name: provider_id + required: true + schema: + type: string + description: The unique ID of the collection provider. + + tags: + - Collection Providers + + responses: + '200': + description: A list of taxonomies. + content: + application/vnd.api+json: + example: + data: + - id: "abc-subject" + type: "taxonomies" + attributes: + text: "Psychology" + parents: [] + - id: "def-subject" + type: "taxonomies" + attributes: + text: "Cognitive Psychology" + parents: ["abc-subject"] + + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to view taxonomies for this provider. + '404': + description: Collection provider not found. + + security: + - CookieAuth: [] diff --git a/swagger-spec/collection_provider/subjects.yaml b/swagger-spec/collection_providers/subjects.yaml similarity index 98% rename from swagger-spec/collection_provider/subjects.yaml rename to swagger-spec/collection_providers/subjects.yaml index 8a9a0c6..1f4175f 100644 --- a/swagger-spec/collection_provider/subjects.yaml +++ b/swagger-spec/collection_providers/subjects.yaml @@ -1,4 +1,4 @@ -# /provider/collections/{collection_id}/subjects/ +# /provider/collections/{provider_id}/subjects/ get: summary: Collections Providers Subject List description: >- @@ -20,7 +20,7 @@ get: - in: path type: string required: true - name: collection_id + name: provider_id description: 'A short id for that collection' tags: - Collection Providers diff --git a/swagger-spec/collection_provider/subjects_highlighted.yaml b/swagger-spec/collection_providers/subjects_highlighted_list.yaml similarity index 96% rename from swagger-spec/collection_provider/subjects_highlighted.yaml rename to swagger-spec/collection_providers/subjects_highlighted_list.yaml index e85b56d..06f39ef 100644 --- a/swagger-spec/collection_provider/subjects_highlighted.yaml +++ b/swagger-spec/collection_providers/subjects_highlighted_list.yaml @@ -1,4 +1,4 @@ -# /provider/collections/{collection_id}/subjects/highlighted/ +# /provider/collections/{provider_id}/subjects/highlighted/ get: summary: Collections Providers Highlighted Subject List description: >- @@ -20,7 +20,7 @@ get: - in: path type: string required: true - name: collection_id + name: provider_id description: 'A short id for that collection' tags: - Collection Providers diff --git a/swagger-spec/collection_provider/submissions.yaml b/swagger-spec/collection_providers/submissions.yaml similarity index 99% rename from swagger-spec/collection_provider/submissions.yaml rename to swagger-spec/collection_providers/submissions.yaml index e8cfa27..8a78336 100644 --- a/swagger-spec/collection_provider/submissions.yaml +++ b/swagger-spec/collection_providers/submissions.yaml @@ -1,4 +1,4 @@ -# /provider/collections/{collection_id}/submissions/ +# /provider/collections/{provider_id}/submissions/ get: summary: Collections Providers Submissions List description: >- @@ -20,7 +20,7 @@ get: - in: path type: string required: true - name: collection_id + name: provider_id description: 'A short id for that collection' tags: - Collection Providers diff --git a/swagger-spec/collection_providers/taxonomies_highlighted_list.yaml b/swagger-spec/collection_providers/taxonomies_highlighted_list.yaml new file mode 100644 index 0000000..8388bb8 --- /dev/null +++ b/swagger-spec/collection_providers/taxonomies_highlighted_list.yaml @@ -0,0 +1,100 @@ +# /provider/collections/{provider_id}/taxonomies/highlighted/ + +get: + summary: List Highlighted Taxonomies for a Collection Provider + description: >- + Retrieve a list of highlighted taxonomies (subjects) for a specific Collection Provider. + + Highlighted taxonomies are curated subjects that appear prominently within a Collection Provider's submission or discovery interface. + + #### Permissions + - No authentication required for public collection providers. + - Authentication required if the collection provider is private or restricted. + + #### Returns + - A JSON object with a `data` key containing an array of taxonomy (subject) resources. + - Each taxonomy describes a subject used to categorize collected metadata and is marked as highlighted. + + tags: + - Collection Providers + - Taxonomies + + operationId: collection_provider_taxonomies_highlighted_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the collection provider. + + - in: query + name: page + type: integer + required: false + description: Page number of results to return (for pagination). + + - in: query + name: per_page + type: integer + required: false + description: Number of results per page. Defaults to 10. + + responses: + '200': + description: Successful retrieval of highlighted taxonomies. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if available). + prev: + type: string + description: Link to the previous page of results (if available). + meta: + type: object + description: Meta information about the response, such as total count. + examples: + application/json: + data: + - id: "psychology" + type: "taxonomy" + attributes: + text: "Psychology" + parent: null + has_children: true + links: + self: "https://api.test.osf.io/v2/taxonomies/psychology/" + - id: "climate_change" + type: "taxonomy" + attributes: + text: "Climate Change" + parent: "environmental_sciences" + has_children: false + links: + self: "https://api.test.osf.io/v2/taxonomies/climate_change/" + links: + self: "https://api.test.osf.io/v2/provider/collections/{provider_id}/taxonomies/highlighted/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access highlighted taxonomies for this collection provider. + '404': + description: Not Found. No collection provider matches the given ID. diff --git a/swagger-spec/collection_providers/taxonomies_list.yaml b/swagger-spec/collection_providers/taxonomies_list.yaml new file mode 100644 index 0000000..b91818d --- /dev/null +++ b/swagger-spec/collection_providers/taxonomies_list.yaml @@ -0,0 +1,87 @@ +# /provider/collections/{provider_id}/taxonomies/ + +get: + summary: List Taxonomies for a Collection Provider + description: >- + Retrieve a list of all taxonomies (subjects) available for a specific collection provider. + + These taxonomies can be used to classify and filter the resources within a collection. + + #### Permissions + - No authentication required for public collection providers. + - Only authorized users can access restricted collection providers. + + #### Returns + - A JSON object with a `data` key containing an array of taxonomy (subject) resources. + - Each taxonomy describes a subject that can be used to categorize collected metadata. + + tags: + - Collection Providers + + operationId: collection_provider_taxonomies_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the collection provider. + + responses: + '200': + description: Successful retrieval of taxonomies for the collection provider. + schema: + type: object + properties: + data: + type: array + items: + $ref: '../taxonomies/definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if available). + prev: + type: string + description: Link to the previous page of results (if available). + meta: + type: object + description: Meta information about the response, such as total count. + examples: + application/json: + data: + - id: "psychology" + type: "taxonomy" + attributes: + text: "Psychology" + parent: null + has_children: true + links: + self: "https://api.test.osf.io/v2/taxonomies/psychology/" + - id: "neuroscience" + type: "taxonomy" + attributes: + text: "Neuroscience" + parent: "psychology" + has_children: false + links: + self: "https://api.test.osf.io/v2/taxonomies/neuroscience/" + links: + self: "https://api.test.osf.io/v2/provider/collections/{provider_id}/taxonomies/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access taxonomies for this collection provider. + '404': + description: Not Found. No collection provider matches the given ID. diff --git a/swagger-spec/preprint_providers/detail.yaml b/swagger-spec/preprint_providers/detail.yaml index c48d4e2..e584ec2 100644 --- a/swagger-spec/preprint_providers/detail.yaml +++ b/swagger-spec/preprint_providers/detail.yaml @@ -66,7 +66,7 @@ get: - in: path type: string required: true - name: preprint_provider_id + name: provider_id description: 'The unique identifier of the preprint provider.' tags: - Preprint Providers diff --git a/swagger-spec/preprint_providers/licenses_list.yaml b/swagger-spec/preprint_providers/licenses_list.yaml index aed4db5..1593ad8 100644 --- a/swagger-spec/preprint_providers/licenses_list.yaml +++ b/swagger-spec/preprint_providers/licenses_list.yaml @@ -25,7 +25,7 @@ get: - in: path type: string required: true - name: preprint_provider_id + name: provider_id description: 'The unique identifier of the preprint provider.' tags: - Preprint Providers diff --git a/swagger-spec/preprint_providers/moderators_detail.yaml b/swagger-spec/preprint_providers/moderators_detail.yaml new file mode 100644 index 0000000..56cda99 --- /dev/null +++ b/swagger-spec/preprint_providers/moderators_detail.yaml @@ -0,0 +1,62 @@ +# /preprint_providers/{provider_id}/moderators/{moderator_id}/ + +get: + summary: Retrieve a Preprint Provider Moderator + description: >- + Retrieve the details of a specific moderator for a given preprint provider, including their permissions and assigned roles. + + #### Permissions + - The authenticated user must be an administrator of the preprint provider. + + #### Returns + - A JSON object with a `data` key containing the moderator details. + - Each moderator includes user details and their permission level. + + tags: + - Preprint Providers + + operationId: preprint_provider_moderator_detail + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + - in: path + name: moderator_id + type: string + required: true + description: The unique identifier of the moderator. + + responses: + '200': + description: Successful retrieval of the moderator details. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "{moderator_id}" + type: "moderators" + attributes: + full_name: "Ada Lovelace" + email: "ada.lovelace@example.com" + permission_group: "admin" + date_added: "2024-01-15T12:34:56Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/{moderator_id}/" + meta: + version: "2.0" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access this moderator. + '404': + description: Not Found. No moderator matches the given ID. diff --git a/swagger-spec/preprint_providers/moderators_list.yaml b/swagger-spec/preprint_providers/moderators_list.yaml new file mode 100644 index 0000000..5e6948c --- /dev/null +++ b/swagger-spec/preprint_providers/moderators_list.yaml @@ -0,0 +1,183 @@ +# /preprint_providers/{provider_id}/moderators/ + +get: + summary: List Moderators for a Preprint Provider + description: >- + Retrieve a list of moderators for a specific preprint provider, including their assigned roles and user information. + + #### Permissions + - The authenticated user must be an administrator of the preprint provider. + + #### Returns + - A JSON object with a `data` key containing a list of moderators. + - Each moderator includes user details and their assigned permission group. + + tags: + - Preprint Providers + + operationId: preprint_provider_moderators_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + responses: + '200': + description: Successful retrieval of moderators. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + example: + data: + - id: "moderator_1" + type: "moderators" + attributes: + full_name: "Ada Lovelace" + email: "ada.lovelace@example.com" + permission_group: "admin" + date_added: "2024-01-15T12:34:56Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_1/" + - id: "moderator_2" + type: "moderators" + attributes: + full_name: "Grace Hopper" + email: "grace.hopper@example.com" + permission_group: "moderator" + date_added: "2024-01-16T09:00:00Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_2/" + meta: + total: 2 + version: "2.0" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access this list of moderators. + '404': + description: Not Found. No preprint provider matches the given ID. + +post: + summary: Add a Moderator to a Preprint Provider + description: >- + Add a new moderator to the preprint provider by specifying the user and their permission group. + + #### Permissions + - The authenticated user must be an administrator of the preprint provider. + + #### Request Body + Provide the `user_id` and `permission_group` in the `attributes` object to create a new moderator assignment. + Available values for `permission_group` are: + - `moderator`: Can review and moderate preprint submissions. + - `admin`: Can manage submissions and other moderators. + + #### Returns + - A JSON object with the new moderator details under the `data` key if the creation is successful. + - If unsuccessful, returns an `errors` object detailing the validation issues. + + tags: + - Preprint Providers + + operationId: preprint_provider_moderators_create + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: object + required: + - type + - attributes + properties: + type: + type: string + enum: + - moderators + description: Must be `moderators`. + attributes: + type: object + required: + - user_id + - permission_group + properties: + user_id: + type: string + description: The unique identifier of the user being added as a moderator. + permission_group: + type: string + enum: + - moderator + - admin + description: | + The permission group for the moderator: + - `moderator`: Can review and moderate preprint submissions. + - `admin`: Can manage submissions and other moderators. + + example: + data: + type: moderators + attributes: + user_id: "user_123" + permission_group: "moderator" + + responses: + '201': + description: Moderator successfully added. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "moderator_3" + type: "moderators" + attributes: + full_name: "Katherine Johnson" + email: "katherine.johnson@example.com" + permission_group: "moderator" + date_added: "2024-01-20T10:15:30Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_3/" + meta: + version: "2.0" + '400': + description: Bad Request. Invalid input provided. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to add a moderator. + '404': + description: Not Found. No preprint provider matches the given ID. + '409': + description: Conflict. The user is already a moderator. diff --git a/swagger-spec/preprint_providers/preprints_list.yaml b/swagger-spec/preprint_providers/preprints_list.yaml index a5923c9..9c6a4fc 100644 --- a/swagger-spec/preprint_providers/preprints_list.yaml +++ b/swagger-spec/preprint_providers/preprints_list.yaml @@ -37,7 +37,7 @@ get: - in: path type: string required: true - name: preprint_provider_id + name: provider_id description: 'The unique identifier of the preprint provider.' tags: - Preprint Providers diff --git a/swagger-spec/preprint_providers/provider_moderator_detail.yaml b/swagger-spec/preprint_providers/provider_moderator_detail.yaml new file mode 100644 index 0000000..1e1a004 --- /dev/null +++ b/swagger-spec/preprint_providers/provider_moderator_detail.yaml @@ -0,0 +1,215 @@ +# /preprint_providers/{provider_id}/moderators/{moderator_id}/ + +get: + summary: Retrieve a Moderator for a Preprint Provider + description: >- + Retrieve the details of a specific moderator for a preprint provider, including their permission group and user information. + + #### Permissions + - The authenticated user must be an administrator of the preprint provider. + + #### Returns + - A JSON object with a `data` key containing the moderator's details. + - Each moderator includes their permission group and basic user information. + + tags: + - Preprint Providers + + operationId: preprint_provider_moderator_detail + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + - in: path + name: moderator_id + type: string + required: true + description: The unique identifier of the moderator. + + responses: + '200': + description: Successful retrieval of the moderator. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "moderator_1" + type: "moderators" + attributes: + full_name: "Ada Lovelace" + email: "ada.lovelace@example.com" + permission_group: "admin" + date_added: "2024-01-15T12:34:56Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_1/" + meta: + version: "2.0" + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access this moderator. + '404': + description: Not Found. No moderator matches the given ID. + +patch: + summary: Update a Moderator's Permission Group for a Preprint Provider + description: >- + Update the permission group for a specific moderator on a preprint provider. + + #### Permissions + - The authenticated user must be an administrator of the preprint provider. + + #### Request Body + Provide the `permission_group` attribute in the `attributes` object to update the moderator. + Available values for `permission_group` are: + - `moderator`: Can review and moderate preprint submissions. + - `admin`: Can manage submissions and other moderators. + + #### Returns + - A JSON object with the updated moderator details under the `data` key if the update is successful. + - If unsuccessful, returns an `errors` object detailing the validation issues. + + tags: + - Preprint Providers + + operationId: preprint_provider_moderator_update + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + - in: path + name: moderator_id + type: string + required: true + description: The unique identifier of the moderator. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: object + required: + - type + - id + - attributes + properties: + type: + type: string + enum: + - moderators + description: Must be `moderators`. + id: + type: string + description: The unique identifier of the moderator. + attributes: + type: object + required: + - permission_group + properties: + permission_group: + type: string + enum: + - moderator + - admin + description: | + The permission group for the moderator: + - `moderator`: Can review and moderate preprint submissions. + - `admin`: Can manage submissions and other moderators. + + example: + data: + type: moderators + id: "{moderator_id}" + attributes: + permission_group: "admin" + + responses: + '200': + description: Moderator successfully updated. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "moderator_1" + type: "moderators" + attributes: + full_name: "Ada Lovelace" + email: "ada.lovelace@example.com" + permission_group: "admin" + date_added: "2024-01-15T12:34:56Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_1/" + meta: + version: "2.0" + '400': + description: Bad Request. Invalid input provided. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to update this moderator. + '404': + description: Not Found. No moderator matches the given ID. + +delete: + summary: Remove a Moderator from a Preprint Provider + description: >- + Remove a moderator from a preprint provider. + + #### Permissions + - The authenticated user must be an administrator of the preprint provider. + + #### Returns + - Returns a `204 No Content` response if the deletion is successful. + - If unsuccessful, returns an `errors` object detailing the issue. + + tags: + - Preprint Providers + + operationId: preprint_provider_moderator_delete + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + - in: path + name: moderator_id + type: string + required: true + description: The unique identifier of the moderator. + + responses: + '204': + description: Moderator successfully removed. No content returned. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to remove this moderator. + '404': + description: Not Found. No moderator matches the given ID. + diff --git a/swagger-spec/preprint_providers/provider_moderator_list.yaml b/swagger-spec/preprint_providers/provider_moderator_list.yaml new file mode 100644 index 0000000..9c889dd --- /dev/null +++ b/swagger-spec/preprint_providers/provider_moderator_list.yaml @@ -0,0 +1,239 @@ +# /preprint_providers/{provider_id}/moderators/ + +get: + summary: List Moderators for a Preprint Provider + description: >- + Retrieve a list of all moderators assigned to a specific preprint provider. + + #### Permissions + - The authenticated user must be an administrator of the preprint provider. + + #### Returns + - A JSON object with a `data` key containing an array of moderator records. + - Each moderator includes their permission group and basic user information. + + tags: + - Preprint Providers + + operationId: preprint_provider_moderator_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + - in: query + name: page + type: integer + required: false + description: Page number of results to view. + + - in: query + name: filter[permission_group] + type: string + required: false + description: Filter moderators by permission group (`moderator` or `admin`). + + responses: + '200': + description: Successful retrieval of the moderators list. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results, if available. + prev: + type: string + description: Link to the previous page of results, if available. + meta: + type: object + description: Meta information about the response, including pagination info. + examples: + application/json: + data: + - id: "moderator_1" + type: "moderators" + attributes: + full_name: "Ada Lovelace" + email: "ada.lovelace@example.com" + permission_group: "admin" + date_added: "2024-01-15T12:34:56Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_1/" + - id: "moderator_2" + type: "moderators" + attributes: + full_name: "Alan Turing" + email: "alan.turing@example.com" + permission_group: "moderator" + date_added: "2024-01-20T10:00:00Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_2/" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/" + next: null + prev: null + meta: + total: 2 + per_page: 10 + page: 1 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access this list. + '404': + description: Not Found. No preprint provider matches the given ID. + +post: + summary: Add a Moderator to a Preprint Provider + description: >- + Add a new moderator to the specified preprint provider. + + #### Permissions + - The authenticated user must be an administrator of the preprint provider. + + #### Request Body + Provide the `permission_group` and the `user_id` for the moderator in the `relationships` object. + + #### Returns + - A JSON object with the newly created moderator details under the `data` key if successful. + - If unsuccessful, returns an `errors` object detailing the validation issues. + + tags: + - Preprint Providers + + operationId: preprint_provider_moderator_create + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + - in: body + name: body + required: true + schema: + type: object + properties: + data: + type: object + required: + - type + - attributes + - relationships + properties: + type: + type: string + enum: + - moderators + description: Must be `moderators`. + attributes: + type: object + required: + - permission_group + properties: + permission_group: + type: string + enum: + - moderator + - admin + description: | + The permission group for the moderator: + - `moderator`: Can review and moderate preprint submissions. + - `admin`: Can manage submissions and other moderators. + relationships: + type: object + required: + - user + properties: + user: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - users + id: + type: string + description: The user ID of the person you wish to add as a moderator. + + example: + data: + type: moderators + attributes: + permission_group: moderator + relationships: + user: + data: + type: users + id: "user_123" + + responses: + '201': + description: Moderator successfully added. + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + id: "moderator_3" + type: "moderators" + attributes: + full_name: "Grace Hopper" + email: "grace.hopper@example.com" + permission_group: "moderator" + date_added: "2024-02-01T14:20:00Z" + relationships: + preprint_provider: + data: + type: "preprint_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_3/" + meta: + version: "2.0" + + '400': + description: Bad Request. Invalid input provided. + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to add a moderator. + '404': + description: Not Found. No preprint provider matches the given ID. + diff --git a/swagger-spec/preprint_providers/provider_subjects_highlighted_list.yaml b/swagger-spec/preprint_providers/provider_subjects_highlighted_list.yaml new file mode 100644 index 0000000..5592428 --- /dev/null +++ b/swagger-spec/preprint_providers/provider_subjects_highlighted_list.yaml @@ -0,0 +1,69 @@ +# /provider/preprints/{provider_id}/subjects/highlighted/ + +get: + summary: List Highlighted Subjects for a Preprint Provider + description: >- + Retrieve a list of highlighted subjects associated with a specific Preprint provider. + + Highlighted subjects are shown prominently on the provider's site and often represent commonly used or recommended categories for submissions. + + #### Permissions + - Publicly accessible. No authentication is required. + + #### Returns + - A JSON object with a `data` key containing an array of subject resources. + - Each subject includes the display name, hierarchical relationships, and additional metadata. + + tags: + - Preprint Providers + + operationId: provider_subjects_highlighted_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the Preprint provider. + responses: + '200': + description: Successful retrieval of the highlighted subjects list. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'subject_definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results, if available. + prev: + type: string + description: Link to the previous page of results, if available. + meta: + type: object + description: Meta information about the response, including pagination info. + examples: + application/json: + data: + - id: "subject_1" + type: "subjects" + attributes: + text: "Psychology" + parents: + - id: "subject_root" + text: "Social Sciences" + has_children: true + highlight: true + relationships: + children: + links: + related: + href: "https://api.test.osf.io/v2/taxonomies/subject_1/chil diff --git a/swagger-spec/preprint_providers/provider_subjects_list.yaml b/swagger-spec/preprint_providers/provider_subjects_list.yaml new file mode 100644 index 0000000..7ae814b --- /dev/null +++ b/swagger-spec/preprint_providers/provider_subjects_list.yaml @@ -0,0 +1,104 @@ +# /provider/preprints/{provider_id}/subjects/ + +get: + summary: List Available Subjects for a Preprint Provider + description: >- + Retrieve a list of all available subjects associated with a specific Preprint provider. + + These subjects can be used to categorize submissions within the provider's Preprint. + Subjects are often organized in a hierarchical taxonomy. + + #### Permissions + - Publicly accessible. No authentication is required. + + #### Returns + - A JSON object with a `data` key containing an array of subject resources. + - Each subject includes its name, parent-child relationships, and additional metadata. + + tags: + - Preprint Providers + + operationId: provider_subjects_list + + parameters: + - in: path + name: collection_id + type: string + required: true + description: The unique identifier of the collection provider. + responses: + '200': + description: Successful retrieval of the subjects list. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'subject_definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results, if available. + prev: + type: string + description: Link to the previous page of results, if available. + meta: + type: object + description: Meta information about the response, including pagination info. + examples: + application/json: + data: + - id: "subject_1" + type: "subjects" + attributes: + text: "Psychology" + parents: + - id: "subject_root" + text: "Social Sciences" + has_children: true + highlight: false + relationships: + children: + links: + related: + href: "https://api.test.osf.io/v2/taxonomies/subject_1/children/" + links: + self: "https://api.test.osf.io/v2/taxonomies/subject_1/" + - id: "subject_3" + type: "subjects" + attributes: + text: "Anthropology" + parents: + - id: "subject_root" + text: "Social Sciences" + has_children: false + highlight: false + relationships: + children: + links: + related: + href: "https://api.test.osf.io/v2/taxonomies/subject_3/children/" + links: + self: "https://api.test.osf.io/v2/taxonomies/subject_3/" + links: + self: "https://api.test.osf.io/v2/provider/preprints/{provider_id}/subjects/" + next: null + prev: null + meta: + total: 2 + per_page: 10 + page: 1 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access this resource. + '404': + description: Not Found. No Preprint provider matches the given ID. diff --git a/swagger-spec/preprint_providers/provider_taxonomies_highlighted_list.yaml b/swagger-spec/preprint_providers/provider_taxonomies_highlighted_list.yaml new file mode 100644 index 0000000..3cd1f98 --- /dev/null +++ b/swagger-spec/preprint_providers/provider_taxonomies_highlighted_list.yaml @@ -0,0 +1,88 @@ +# /preprint_providers/{provider_id}/taxonomies/highlighted/ + +get: + summary: List Highlighted Taxonomies for a Preprint Provider + description: >- + Retrieve a list of highlighted taxonomies (subjects) for a specific preprint provider. + + Highlighted taxonomies are the primary subjects that the preprint provider chooses to showcase for organizing and filtering preprints. + + #### Permissions + - No authentication required for public providers. + - Only authorized users can access restricted providers. + + #### Returns + - A JSON object with a `data` key containing an array of taxonomy resources. + - Each taxonomy represents a subject that can be assigned to preprints. + + tags: + - Preprint Providers + - Taxonomies + + operationId: preprint_provider_taxonomies_highlighted_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + responses: + '200': + description: Successful retrieval of highlighted taxonomies. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if applicable). + prev: + type: string + description: Link to the previous page of results (if applicable). + meta: + type: object + description: Meta information about the response (e.g., total number of results). + examples: + application/json: + data: + - id: "sociology" + type: "taxonomy" + attributes: + text: "Sociology" + parent: null + has_children: true + links: + self: "https://api.test.osf.io/v2/taxonomies/sociology/" + - id: "psychology" + type: "taxonomy" + attributes: + text: "Psychology" + parent: null + has_children: true + links: + self: "https://api.test.osf.io/v2/taxonomies/psychology/" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/taxonomies/highlighted/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access taxonomies for this provider. + '404': + description: Not Found. No preprint provider matches the given ID. diff --git a/swagger-spec/preprint_providers/provider_taxonomies_list.yaml b/swagger-spec/preprint_providers/provider_taxonomies_list.yaml new file mode 100644 index 0000000..1ded87d --- /dev/null +++ b/swagger-spec/preprint_providers/provider_taxonomies_list.yaml @@ -0,0 +1,88 @@ +# /preprint_providers/{provider_id}/taxonomies/ + +get: + summary: List Taxonomies for a Preprint Provider + description: >- + Retrieve a list of all taxonomies (subjects) associated with a specific preprint provider. + + These taxonomies can be used to categorize and filter preprints submitted to this provider. + + #### Permissions + - No authentication required for public providers. + - Only authorized users can access restricted providers. + + #### Returns + - A JSON object with a `data` key containing an array of taxonomy resources. + - Each taxonomy represents a subject that can be assigned to preprints. + + tags: + - Preprint Providers + - Taxonomies + + operationId: preprint_provider_taxonomies_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + responses: + '200': + description: Successful retrieval of taxonomies for the preprint provider. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if applicable). + prev: + type: string + description: Link to the previous page of results (if applicable). + meta: + type: object + description: Meta information about the response (e.g., total number of results). + examples: + application/json: + data: + - id: "engineering" + type: "taxonomy" + attributes: + text: "Engineering" + parent: null + has_children: true + links: + self: "https://api.test.osf.io/v2/taxonomies/engineering/" + - id: "biology" + type: "taxonomy" + attributes: + text: "Biology" + parent: null + has_children: true + links: + self: "https://api.test.osf.io/v2/taxonomies/biology/" + links: + self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/taxonomies/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access taxonomies for this provider. + '404': + description: Not Found. No preprint provider matches the given ID. diff --git a/swagger-spec/preprint_providers/providers_citation_styles.yaml b/swagger-spec/preprint_providers/providers_citation_styles.yaml new file mode 100644 index 0000000..165a3c9 --- /dev/null +++ b/swagger-spec/preprint_providers/providers_citation_styles.yaml @@ -0,0 +1,105 @@ +# /providers/preprints/{provider_id}/citation_styles/ + +get: + summary: List Citation Styles for a Preprint Provider + description: >- + Retrieve a list of citation styles supported by a specific preprint provider. + + These citation styles can be used to generate formatted citations for preprints associated with this provider. + + #### Permissions + - No authentication required for public providers. + - Only authorized users can access restricted providers. + + #### Returns + - A JSON object with a `data` key containing an array of citation style resources. + - Each citation style includes its ID, title, and whether it is the default style. + + tags: + - Preprint Providers + + operationId: providers_preprint_citation_styles_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + + - in: query + name: filter[default] + type: boolean + required: false + description: Filter citation styles by whether they are marked as default. + + - in: query + name: page + type: integer + required: false + description: Page number of results to return (for pagination). + + - in: query + name: per_page + type: integer + required: false + description: Number of results per page. Defaults to 10. + + responses: + '200': + description: Successful retrieval of citation styles. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if applicable). + prev: + type: string + description: Link to the previous page of results (if applicable). + meta: + type: object + description: Meta information about the response (e.g., total number of results). + examples: + application/json: + data: + - id: "apa" + type: "citation-style" + attributes: + title: "APA 7th Edition" + short_name: "APA" + default: true + links: + self: "https://api.test.osf.io/v2/citations/styles/apa/" + - id: "mla" + type: "citation-style" + attributes: + title: "MLA 8th Edition" + short_name: "MLA" + default: false + links: + self: "https://api.test.osf.io/v2/citations/styles/mla/" + links: + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/citation_styles/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access citation styles for this provider. + '404': + description: Not Found. No preprint provider matches the given ID. diff --git a/swagger-spec/preprint_providers/subjects_highlighted_list.yaml b/swagger-spec/preprint_providers/subjects_highlighted_list.yaml new file mode 100644 index 0000000..e69de29 diff --git a/swagger-spec/preprint_providers/taxonomies_list.yaml b/swagger-spec/preprint_providers/subjects_list.yaml similarity index 98% rename from swagger-spec/preprint_providers/taxonomies_list.yaml rename to swagger-spec/preprint_providers/subjects_list.yaml index b8448a1..77c3c79 100644 --- a/swagger-spec/preprint_providers/taxonomies_list.yaml +++ b/swagger-spec/preprint_providers/subjects_list.yaml @@ -27,7 +27,7 @@ get: - in: path type: string required: true - name: preprint_provider_id + name: provider_id description: 'The unique identifier of the preprint provider.' tags: - Preprint Providers diff --git a/swagger-spec/preprint_providers/withdraw_requests.yaml b/swagger-spec/preprint_providers/withdraw_requests.yaml new file mode 100644 index 0000000..64f5e17 --- /dev/null +++ b/swagger-spec/preprint_providers/withdraw_requests.yaml @@ -0,0 +1,115 @@ +# /providers/preprints/{provider_id}/withdraw_requests/ + +get: + summary: List Withdraw Requests for a Preprint Provider + description: >- + Retrieve a list of withdraw requests for a specific preprint provider. + + Withdraw requests are initiated by contributors to request the withdrawal of a preprint from public view. + These requests require moderation and can be either approved or rejected by provider moderators. + + #### Permissions + - Admins and moderators for the provider can view all withdraw requests. + - Unauthorized users will receive a `403 Forbidden` response. + + #### Returns + - A JSON object with a `data` key containing an array of withdraw request resources. + - Each withdraw request includes the current state, the associated preprint, and relevant timestamps. + + tags: + - Preprint Providers + + operationId: provider_preprints_withdraw_requests_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the preprint provider. + responses: + '200': + description: Successful retrieval of withdraw requests. + schema: + type: object + properties: + data: + type: array + items: + $ref: 'definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if applicable). + prev: + type: string + description: Link to the previous page of results (if applicable). + meta: + type: object + description: Meta information about the response (e.g., total number of results). + examples: + application/json: + data: + - id: "wrq_1234" + type: "withdraw-request" + attributes: + state: "pending" + justification: "Authors discovered a critical error." + date_submitted: "2024-10-15T14:12:00Z" + date_reviewed: null + relationships: + preprint: + data: + type: "preprints" + id: "preprint_5678" + provider: + data: + type: "preprint_providers" + id: "{provider_id}" + reviews_state: + data: + type: "reviews_state" + id: "pending" + links: + self: "https://api.test.osf.io/v2/withdraw_requests/wrq_1234/" + - id: "wrq_5678" + type: "withdraw-request" + attributes: + state: "accepted" + justification: "Plagiarism identified." + date_submitted: "2024-09-20T08:05:00Z" + date_reviewed: "2024-09-25T16:45:00Z" + relationships: + preprint: + data: + type: "preprints" + id: "preprint_9101" + provider: + data: + type: "preprint_providers" + id: "{provider_id}" + reviews_state: + data: + type: "reviews_state" + id: "accepted" + links: + self: "https://api.test.osf.io/v2/withdraw_requests/wrq_5678/" + links: + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/withdraw_requests/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access withdraw requests for this provider. + '404': + description: Not Found. No preprint provider matches the given ID. diff --git a/swagger-spec/preprints/definition.yaml b/swagger-spec/preprints/definition.yaml index 4cc1600..94af91f 100644 --- a/swagger-spec/preprints/definition.yaml +++ b/swagger-spec/preprints/definition.yaml @@ -234,4 +234,4 @@ example: provider: data: type: providers - id: '{preprint_provider_id}' + id: '{provider_id}' diff --git a/swagger-spec/registration_providers/moderators_detail.yaml b/swagger-spec/registration_providers/moderators_detail.yaml new file mode 100644 index 0000000..24847cf --- /dev/null +++ b/swagger-spec/registration_providers/moderators_detail.yaml @@ -0,0 +1,105 @@ +get: + summary: Retrieve Moderator Details + description: | + Retrieves details about a moderator associated with a provider. + tags: + - Registration Providers + parameters: + - name: provider_id + in: path + required: true + type: string + description: The unique identifier of the provider. + - name: moderator_id + in: path + required: true + type: string + description: The unique identifier of the moderator. + responses: + '200': + description: Moderator details retrieved successfully. + examples: + application/vnd.api+json: + data: + id: "abcde" + type: "moderators" + attributes: + full_name: "Jane Doe" + permission_group: "moderator" + email: "jane.doe@example.com" + '403': + description: Forbidden – insufficient permissions. + '404': + description: Not found – moderator does not exist. + +patch: + summary: Update Moderator Permissions + description: | + Updates the permissions of a moderator associated with a provider. + tags: + - Registration Providers + parameters: + - name: provider_id + in: path + required: true + type: string + - name: moderator_id + in: path + required: true + type: string + - in: body + name: body + required: true + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + - attributes + properties: + type: + type: string + enum: ["moderators"] + id: + type: string + attributes: + type: object + properties: + permission_group: + type: string + enum: ["moderator", "admin"] + responses: + '200': + description: Moderator permissions updated successfully. + '400': + description: Invalid request – validation errors. + '403': + description: Forbidden – insufficient permissions. + +delete: + summary: Remove Moderator + description: | + Removes a moderator from the specified provider. + tags: + - Registration Providers + parameters: + - name: provider_id + in: path + required: true + type: string + - name: moderator_id + in: path + required: true + type: string + responses: + '204': + description: Moderator removed successfully. + '403': + description: Forbidden – insufficient permissions. + '404': + description: Not found – moderator does not exist. diff --git a/swagger-spec/registration_providers/moderators_list.yaml b/swagger-spec/registration_providers/moderators_list.yaml new file mode 100644 index 0000000..cd2aff3 --- /dev/null +++ b/swagger-spec/registration_providers/moderators_list.yaml @@ -0,0 +1,73 @@ +get: + summary: List Moderators + description: | + Retrieves a list of moderators associated with a provider. + tags: + - Registration Providers + parameters: + - name: provider_id + in: path + required: true + type: string + responses: + '200': + description: List of moderators retrieved successfully. + examples: + application/vnd.api+json: + data: + - id: "abcde" + type: "moderators" + attributes: + full_name: "Jane Doe" + permission_group: "moderator" + - id: "fghij" + type: "moderators" + attributes: + full_name: "John Smith" + permission_group: "admin" + +post: + summary: Add Moderator + description: | + Adds a moderator to the specified provider. + tags: + - Registration Providers + parameters: + - name: provider_id + in: path + required: true + type: string + - in: body + name: body + required: true + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + - attributes + properties: + type: + type: string + enum: ["moderators"] + id: + type: string + description: User ID to add as moderator. + attributes: + type: object + properties: + permission_group: + type: string + enum: ["moderator", "admin"] + responses: + '201': + description: Moderator added successfully. + '400': + description: Invalid request – user already moderator or invalid data. + '403': + description: Forbidden – insufficient permissions. diff --git a/swagger-spec/registration_providers/provider_taxonomies_highlitghted_list.yaml b/swagger-spec/registration_providers/provider_taxonomies_highlitghted_list.yaml new file mode 100644 index 0000000..8d88ef5 --- /dev/null +++ b/swagger-spec/registration_providers/provider_taxonomies_highlitghted_list.yaml @@ -0,0 +1,25 @@ +get: + summary: List Highlighted Taxonomies + description: | + Retrieves highlighted taxonomies associated with the provider. + tags: + - Registration Providers + parameters: + - name: provider_id + in: path + required: true + type: string + responses: + '200': + description: Highlighted taxonomies retrieved successfully. + examples: + application/vnd.api+json: + data: + - id: "12345" + type: "taxonomies" + attributes: + text: "Psychology" + - id: "67890" + type: "taxonomies" + attributes: + text: "Sociology" diff --git a/swagger-spec/registration_providers/provider_taxonomies_list.yaml b/swagger-spec/registration_providers/provider_taxonomies_list.yaml new file mode 100644 index 0000000..fa4789c --- /dev/null +++ b/swagger-spec/registration_providers/provider_taxonomies_list.yaml @@ -0,0 +1,30 @@ +get: + summary: List Provider Taxonomies + description: | + Retrieves a list of all taxonomies associated with the provider. + tags: + - Registration Providers + parameters: + - name: provider_id + in: path + required: true + type: string + - name: filter[parent] + in: query + required: false + type: string + description: Filter by parent taxonomy ID ('null' for top-level). + responses: + '200': + description: Taxonomies retrieved successfully. + examples: + application/vnd.api+json: + data: + - id: "23456" + type: "taxonomies" + attributes: + text: "Life Sciences" + - id: "34567" + type: "taxonomies" + attributes: + text: "Social Sciences" diff --git a/swagger-spec/registration_providers/registration_actions_list.yaml b/swagger-spec/registration_providers/registration_actions_list.yaml new file mode 100644 index 0000000..50345f0 --- /dev/null +++ b/swagger-spec/registration_providers/registration_actions_list.yaml @@ -0,0 +1,122 @@ +# /registrations/{provider_id}/actions/ + +get: + summary: List Registration Actions + description: >- + Retrieve a list of actions associated with a specific registration. + + Registration Actions represent moderator decisions or contributor responses related to the registration workflow. + These actions log the decision history for registrations requiring moderation or contributor approval. + + #### Permissions + - Public registrations: No authentication required. + - Private registrations: Only contributors with read access may view registration actions. + + #### Returns + - A JSON object with a `data` key containing an array of registration action resources. + - Registration actions describe the decision history, who performed the action, when, and the resulting state of the registration. + + tags: + - Registration Providers + + operationId: registration_actions_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration. + + - in: query + name: page + type: integer + required: false + description: Page number of results to return (for pagination). + + - in: query + name: per_page + type: integer + required: false + description: Number of results per page. Defaults to 10. + + responses: + '200': + description: Successful retrieval of registration actions. + schema: + type: object + properties: + data: + type: array + items: + $ref: './definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if available). + prev: + type: string + description: Link to the previous page of results (if available). + meta: + type: object + description: Meta information about the response, such as total count. + examples: + application/json: + data: + - id: "ract1" + type: "registration_action" + attributes: + trigger: "submit" + comment: "Initial submission" + from_state: "draft" + to_state: "unapproved" + date_created: "2024-05-01T12:00:00Z" + relationships: + creator: + data: + type: "users" + id: "user123" + target: + data: + type: "registrations" + id: "reg1" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/actions/ract1/" + - id: "ract2" + type: "registration_action" + attributes: + trigger: "accept" + comment: "Moderator approved" + from_state: "pending_moderation" + to_state: "approved" + date_created: "2024-05-03T14:45:00Z" + relationships: + creator: + data: + type: "users" + id: "moderator1" + target: + data: + type: "registrations" + id: "reg1" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/actions/ract2/" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/actions/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access these registration actions. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registration_providers/registration_requests_list.yaml b/swagger-spec/registration_providers/registration_requests_list.yaml new file mode 100644 index 0000000..2c17fc5 --- /dev/null +++ b/swagger-spec/registration_providers/registration_requests_list.yaml @@ -0,0 +1,110 @@ +# /registrations/{provider_id}/requests/ + +get: + summary: List Registration Requests + description: >- + Retrieve a list of requests associated with a specific registration. + + Registration Requests represent user-initiated requests that may include withdrawal requests or requests for changes. + These requests are typically part of moderated workflows and require approval or rejection by moderators or contributors. + + ## Permissions + - Public registrations: No authentication required to view public requests. + - Private registrations: Only contributors with read access may view registration requests. + - Moderators of the registration provider may view all requests, including pending ones. + + ## Returns + - A JSON object with a `data` key containing an array of registration request resources. + - Each request describes the request type, status, creator, and any related comments. + + tags: + - Registration Providers + + operationId: registration_requests_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration. + + + responses: + '200': + description: Successful retrieval of registration requests. + schema: + type: object + properties: + data: + type: array + items: + $ref: './definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if available). + prev: + type: string + description: Link to the previous page of results (if available). + meta: + type: object + description: Meta information about the response, such as total count. + examples: + application/json: + data: + - id: "req1" + type: "registration_request" + attributes: + request_type: "withdrawal" + state: "pending" + justification: "Authors requested withdrawal due to data issues." + date_created: "2024-06-01T09:30:00Z" + relationships: + creator: + data: + type: "users" + id: "user123" + target: + data: + type: "registrations" + id: "reg1" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/requests/req1/" + - id: "req2" + type: "registration_request" + attributes: + request_type: "withdrawal" + state: "accepted" + justification: "Withdrawal approved by moderator." + date_created: "2024-06-05T15:45:00Z" + relationships: + creator: + data: + type: "users" + id: "moderator1" + target: + data: + type: "registrations" + id: "reg1" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/requests/req2/" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/requests/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access these registration requests. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registration_providers/registrations_list.yaml b/swagger-spec/registration_providers/registrations_list.yaml new file mode 100644 index 0000000..16ff05b --- /dev/null +++ b/swagger-spec/registration_providers/registrations_list.yaml @@ -0,0 +1,108 @@ +# /registrations/{provider_id}/requests/ + +get: + summary: List Registration Requests + description: >- + Retrieve a list of requests associated with a specific registration. + + Registration Requests represent user-initiated requests that may include withdrawal requests or requests for changes. + These requests are typically part of moderated workflows and require approval or rejection by moderators or contributors. + + #### Permissions + - Public registrations: No authentication required to view public requests. + - Private registrations: Only contributors with read access may view registration requests. + - Moderators of the registration provider may view all requests, including pending ones. + + #### Returns + - A JSON object with a `data` key containing an array of registration request resources. + - Each request describes the request type, status, creator, and any related comments. + + tags: + - Registration Providers + + operationId: registration_requests_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration. + responses: + '200': + description: Successful retrieval of registration requests. + schema: + type: object + properties: + data: + type: array + items: + $ref: './definition.yaml' + links: + type: object + properties: + self: + type: string + description: Link to the current page of results. + next: + type: string + description: Link to the next page of results (if available). + prev: + type: string + description: Link to the previous page of results (if available). + meta: + type: object + description: Meta information about the response, such as total count. + examples: + application/json: + data: + - id: "req1" + type: "registration_request" + attributes: + request_type: "withdrawal" + state: "pending" + justification: "Authors requested withdrawal due to data issues." + date_created: "2024-06-01T09:30:00Z" + relationships: + creator: + data: + type: "users" + id: "user123" + target: + data: + type: "registrations" + id: "reg1" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/requests/req1/" + - id: "req2" + type: "registration_request" + attributes: + request_type: "withdrawal" + state: "accepted" + justification: "Withdrawal approved by moderator." + date_created: "2024-06-05T15:45:00Z" + relationships: + creator: + data: + type: "users" + id: "moderator1" + target: + data: + type: "registrations" + id: "reg1" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/requests/req2/" + links: + self: "https://api.test.osf.io/v2/registrations/reg1/requests/" + next: null + prev: null + meta: + total: 2 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required. + '403': + description: Forbidden. You do not have permission to access these registration requests. + '404': + description: Not Found. No registration matches the given ID. diff --git a/swagger-spec/registration_providers/registrations_schema_list.yaml b/swagger-spec/registration_providers/registrations_schema_list.yaml new file mode 100644 index 0000000..888da64 --- /dev/null +++ b/swagger-spec/registration_providers/registrations_schema_list.yaml @@ -0,0 +1,132 @@ +# /schemas/registrations/ +get: + summary: List Registration Schemas + description: >- + Retrieve a list of all available Registration Schemas. + + Registration Schemas define the structure and content of registration forms. Each schema outlines the fields that users must complete when registering an OSF project. Schemas may include required and optional questions, supporting different types of research workflows and data collections. + + Registration Schemas are maintained by the Center for Open Science and approved affiliated institutions. Some schemas are globally available, while others may be specific to certain providers. + + #### Permissions + - Public endpoint. No authentication required. + - All registration schemas are available to any user. + + #### Returns + - A JSON object with a `data` key containing an array of registration schemas. + - Each schema includes metadata such as name, description, and schema versioning information. + + tags: + - Registration Providers + + operationId: registrations_schema_list + + parameters: + - in: query + name: page + type: integer + required: false + description: Page number of results to return (pagination). + + - in: query + name: per_page + type: integer + required: false + description: Number of results per page (default 10, maximum 100). + + - in: query + name: filter[name] + type: string + required: false + description: Filter registration schemas by their name. + + - in: query + name: filter[active] + type: boolean + required: false + description: Filter registration schemas by their active status (`true` or `false`). + + responses: + '200': + description: Successful retrieval of registration schemas. + schema: + type: object + properties: + data: + type: array + items: + $ref: './definition.yaml' + links: + type: object + properties: + self: + type: string + next: + type: string + description: URL to the next page of results (if applicable). + prev: + type: string + description: URL to the previous page of results (if applicable). + meta: + type: object + properties: + total: + type: integer + description: Total number of registration schemas available. + per_page: + type: integer + description: Number of schemas returned per page. + version: + type: string + description: API version. + + examples: + application/json: + data: + - id: "prereg-challenge" + type: "registration_schemas" + attributes: + name: "Prereg Challenge" + description: "A schema supporting pre-registration of research plans for the Preregistration Challenge." + schema_version: 1 + active: true + schema: + - id: "q1" + type: "object" + title: "Research Questions" + properties: + text: "What is the main research question or hypothesis?" + date_created: "2017-06-01T00:00:00Z" + date_modified: "2023-10-01T00:00:00Z" + links: + self: "https://api.test.osf.io/v2/schemas/registrations/prereg-challenge/" + - id: "osf-registration" + type: "registration_schemas" + attributes: + name: "OSF-Standard Registration" + description: "The default OSF registration schema for general use." + schema_version: 2 + active: true + schema: + - id: "q1" + type: "object" + title: "Purpose of Registration" + properties: + text: "What is the purpose of this registration?" + date_created: "2015-01-01T00:00:00Z" + date_modified: "2024-01-01T00:00:00Z" + links: + self: "https://api.test.osf.io/v2/schemas/registrations/osf-registration/" + links: + self: "https://api.test.osf.io/v2/schemas/registrations/" + next: "https://api.test.osf.io/v2/schemas/registrations/?page=2" + prev: null + meta: + total: 25 + per_page: 10 + version: "2.0" + + '400': + description: Bad Request. Invalid input provided. + '404': + description: Not Found. No registration schemas match the given parameters. diff --git a/swagger-spec/registration_providers/registrations_subjects_list.yaml b/swagger-spec/registration_providers/registrations_subjects_list.yaml new file mode 100644 index 0000000..591a509 --- /dev/null +++ b/swagger-spec/registration_providers/registrations_subjects_list.yaml @@ -0,0 +1,126 @@ +# /registrations/{provider_id}/subjects/ +get: + summary: List Subjects for a Registration + description: >- + Retrieve a list of subjects (taxonomy terms) assigned to a specific registration. + + Subjects are used to categorize the content of a registration according to a predefined taxonomy. + Each subject may be a part of a hierarchical structure, allowing for detailed categorization. + + #### Permissions + - Public registrations: No authentication required. + - Private registrations: Only contributors with read access can view subjects. + + #### Returns + - A JSON object with a `data` key containing an array of subjects. + - Each subject includes metadata such as the subject text and its hierarchical position. + + tags: + - Registration Providers + + operationId: registrations_subjects_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration. + + - in: query + name: page + type: integer + required: false + description: Page number of results to return (pagination). + + - in: query + name: per_page + type: integer + required: false + description: Number of results per page (default 10, maximum 100). + + responses: + '200': + description: Successful retrieval of subjects for the registration. + schema: + type: object + properties: + data: + type: array + items: + $ref: '../taxonomies/definition.yaml' + links: + type: object + properties: + self: + type: string + next: + type: string + description: URL to the next page of results (if applicable). + prev: + type: string + description: URL to the previous page of results (if applicable). + meta: + type: object + properties: + total: + type: integer + description: Total number of subjects assigned to this registration. + per_page: + type: integer + description: Number of subjects returned per page. + version: + type: string + description: API version. + + examples: + application/json: + data: + - id: "12345" + type: "subjects" + attributes: + text: "Psychology" + parent: null + children: + - id: "67890" + text: "Cognitive Psychology" + relationships: + children: + links: + related: "https://api.test.osf.io/v2/taxonomies/12345/children/" + parent: + links: + related: null + links: + self: "https://api.test.osf.io/v2/taxonomies/12345/" + - id: "67890" + type: "subjects" + attributes: + text: "Cognitive Psychology" + parent: "Psychology" + children: [] + relationships: + parent: + links: + related: "https://api.test.osf.io/v2/taxonomies/12345/" + children: + links: + related: null + links: + self: "https://api.test.osf.io/v2/taxonomies/67890/" + links: + self: "https://api.test.osf.io/v2/registrations/abcd1/subjects/" + next: null + prev: null + meta: + total: 2 + per_page: 10 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required to access this registration's subjects. + '403': + description: Forbidden. You do not have permission to access subjects for this registration. + '404': + description: Not Found. No registration matches the given ID. + diff --git a/swagger-spec/registration_providers/registrations_submissions_list.yaml b/swagger-spec/registration_providers/registrations_submissions_list.yaml new file mode 100644 index 0000000..4a1d691 --- /dev/null +++ b/swagger-spec/registration_providers/registrations_submissions_list.yaml @@ -0,0 +1,138 @@ +# /registrations/{provider_id}/submissions/ +get: + summary: List Submissions for a Registration + description: >- + Retrieve a list of submissions associated with a specific registration. + A submission represents an attempt to add a registration to a collection, typically requiring moderation or approval. + + #### Permissions + - Only authenticated users with access to the registration can view submission data. + - Access to submission details may depend on the moderation settings of the related collections. + + #### Returns + - A JSON object with a `data` key containing an array of submission objects. + - Each submission reflects its current moderation status and relevant metadata. + + tags: + - Registrations + - Collection Submissions + + operationId: registrations_submissions_list + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the registration. + + - in: query + name: filter[state] + type: string + required: false + description: | + Filter submissions by their state. + Available values: + - `in_progress` + - `pending` + - `accepted` + - `rejected` + - `removed` + + - in: query + name: page + type: integer + required: false + description: Page number of results to return (pagination). + + - in: query + name: per_page + type: integer + required: false + description: Number of results per page (default 10, maximum 100). + + responses: + '200': + description: Successful retrieval of the list of submissions for the registration. + schema: + type: object + properties: + data: + type: array + items: + $ref: '../collection_submissions/definition.yaml' + links: + type: object + properties: + self: + type: string + next: + type: string + description: Link to the next page of results, if applicable. + prev: + type: string + description: Link to the previous page of results, if applicable. + meta: + type: object + properties: + total: + type: integer + description: Total number of submissions. + per_page: + type: integer + description: Number of submissions per page. + version: + type: string + description: API version. + + examples: + application/json: + data: + - id: "sub1" + type: "collection-submissions" + attributes: + state: "pending" + date_submitted: "2024-12-01T12:00:00Z" + relationships: + collection: + data: + type: "collections" + id: "col123" + creator: + data: + type: "users" + id: "user456" + links: + self: "https://api.test.osf.io/v2/collection_submissions/sub1/" + - id: "sub2" + type: "collection-submissions" + attributes: + state: "accepted" + date_submitted: "2024-10-15T10:00:00Z" + relationships: + collection: + data: + type: "collections" + id: "col456" + creator: + data: + type: "users" + id: "user456" + links: + self: "https://api.test.osf.io/v2/collection_submissions/sub2/" + links: + self: "https://api.test.osf.io/v2/registrations/abcd1/submissions/" + next: null + prev: null + meta: + total: 2 + per_page: 10 + version: "2.0" + + '401': + description: Unauthorized. Authentication is required to access these submissions. + '403': + description: Forbidden. You do not have permission to view these submissions. + '404': + description: Not Found. No registration matches the given ID. + diff --git a/swagger-spec/registration_providers/subjects_highlighted_list.yaml b/swagger-spec/registration_providers/subjects_highlighted_list.yaml new file mode 100644 index 0000000..d6f4238 --- /dev/null +++ b/swagger-spec/registration_providers/subjects_highlighted_list.yaml @@ -0,0 +1,25 @@ +get: + summary: List Highlighted Subjects + description: | + Retrieves highlighted subjects for the specified provider. + tags: + - Registration Providers + parameters: + - name: provider_id + in: path + required: true + type: string + responses: + '200': + description: Highlighted subjects retrieved successfully. + examples: + application/vnd.api+json: + data: + - id: "54321" + type: "subjects" + attributes: + text: "Clinical Psychology" + - id: "98765" + type: "subjects" + attributes: + text: "Neuroscience" diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 20ea459..e8a1d63 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -839,7 +839,7 @@ tags: - `cancel` is used to cancel a Collection Submission in a `pending` state, reverting it back to the `in_progress`. - - name: Collection Submissions Provider + - name: Collection Providers description: >- A Collection Submissions Provider represents the data for moderators and admins for a group of collections. It acts as a central hub for managing all collection submissions within various collections, ensuring that @@ -854,8 +854,50 @@ tags: adheres to the standards set for collection submissions. It aids in providing transparency and order to the process of managing collections and ensures that moderators and admins have the tools and information they need to effectively manage collection submissions. - - + - name: Registration Providers + description: >- + Registration Providers are entities that manage and moderate groups of registrations on the OSF platform. + + Each Registration Provider defines workflows, review policies, and customization options for their collection of registrations. Registration Providers can be configured to operate in different moderation modes, such as pre-moderation, post-moderation, or automated workflows. + + Registration Providers may also specify accepted license types, registration schemas, taxonomies, and review workflows for their associated registrations. They allow communities or organizations to manage the visibility and curation of registered research within their domain. + + **Attributes include:** + - `id`: The unique identifier for the registration provider. + - `name`: Human-readable name of the provider. + - `description`: A description of the provider’s purpose and scope. + - `reviews_workflow`: Defines the moderation workflow type (e.g., pre-moderation, post-moderation). + - `allow_submissions`: Boolean indicating whether new registrations can be submitted. + - `licenses_acceptable`: List of licenses accepted by the provider. + + **Endpoints include:** + - List and detail views of Registration Providers. + - Access to registrations under a given provider. + - Access to registration schemas and licenses supported by a provider. + - Management of moderators and submission actions within the provider's moderation system. + + - name: Preprint Providers + description: >- + Preprint Providers are entities that manage and moderate groups of preprints on the OSF platform. + + Each Preprint Provider oversees its own preprint service, which can include branding, theming, subject areas, moderation workflows, and licensing policies. Preprint Providers are often affiliated with journals, societies, or research communities and enable researchers to share early versions of their work. + + Preprint Providers can implement customizable review and moderation workflows, as well as curate the preprints submitted to their service. Providers can also specify submission requirements, allowable licenses, and taxonomies for classifying preprints. + + **Attributes include:** + - `id`: The unique identifier for the preprint provider. + - `name`: Human-readable name of the provider. + - `description`: A description of the provider’s purpose and scope. + - `reviews_workflow`: Defines the moderation workflow type (e.g., pre-moderation, post-moderation). + - `allow_submissions`: Boolean indicating whether new preprints can be submitted. + - `licenses_acceptable`: List of licenses accepted by the provider. + - `social_links`: Optional links to provider social media (e.g., Twitter, Facebook). + + **Endpoints include:** + - List and detail views of Preprint Providers. + - Access to preprints associated with a given provider. + - Access to taxonomies and licenses supported by a provider. + - Management of moderators and submission actions within the provider's moderation system. paths: @@ -1128,8 +1170,6 @@ paths: /preprints/{preprint_id}/relationships/institutions/: $ref: 'preprints/institutions_relationship_list.yaml' - - ########################## # PREPRINT PROVIDERS # ########################## @@ -1137,18 +1177,33 @@ paths: /preprint_providers/: $ref: 'preprint_providers/list.yaml' - /preprint_providers/{preprint_provider_id}/: + /preprint_providers/{provider_id}/: $ref: 'preprint_providers/detail.yaml' - /preprint_providers/{preprint_provider_id}/preprints/: + /preprint_providers/{provider_id}/preprints/: $ref: 'preprint_providers/preprints_list.yaml' - /preprint_providers/{preprint_provider_id}/taxonomies/: - $ref: 'preprint_providers/taxonomies_list.yaml' + /preprint_providers/{provider_id}/taxonomies/: + $ref: 'preprint_providers/provider_taxonomies_list.yaml' - /preprint_providers/{preprint_provider_id}/licenses/: + /preprint_providers/{provider_id}/taxonomies/highlighted/: + $ref: 'preprint_providers/provider_taxonomies_highlighted_list.yaml' + + /providers/preprints/{provider_id}/citation_styles/: + $ref: 'preprint_providers/providers_citation_styles.yaml' + + /preprint_providers/{provider_id}/licenses/: $ref: 'preprint_providers/licenses_list.yaml' + /preprint_providers/{provider_id}/moderators/: + $ref: 'preprint_providers/provider_moderator_list.yaml' + + /preprint_providers/{provider_id}/moderators/{moderator_id}/: + $ref: 'preprint_providers/provider_moderator_detail.yaml' + + /providers/preprints/{provider_id}/withdraw_requests/: + $ref: 'preprint_providers/withdraw_requests.yaml' + ##################### # REGISTRATIONS # ##################### @@ -1354,25 +1409,25 @@ paths: ############################ /provider/collections/: - $ref: 'collection_provider/list.yaml' + $ref: 'collection_providers/list.yaml' - /provider/collections/{collection_id}/: - $ref: 'collection_provider/detail.yaml' + /provider/collections/{provider_id}/: + $ref: 'collection_providers/detail.yaml' - /provider/collections/{collection_id}/licenses/: - $ref: 'collection_provider/licenses.yaml' + /provider/collections/{provider_id}/licenses/: + $ref: 'collection_providers/licenses.yaml' - /provider/collections/{collection_id}/submissions/: - $ref: 'collection_provider/submissions.yaml' + /provider/collections/{provider_id}/submissions/: + $ref: 'collection_providers/submissions.yaml' - /provider/collections/{collection_id}/subjects/: - $ref: 'collection_provider/subjects.yaml' + /provider/collections/{provider_id}/subjects/: + $ref: 'collection_providers/subjects.yaml' - /provider/collections/{collection_id}/subjects/highlighted/: - $ref: 'collection_provider/subjects_highlighted.yaml' + /provider/collections/{provider_id}/subjects/highlighted/: + $ref: 'collection_providers/subjects_highlighted_list.yaml' - /provider/collections/{collection_id}/moderators/: - $ref: 'collection_provider/moderators_list.yaml' + /provider/collections/{provider_id}/moderators/: + $ref: 'collection_providers/moderators_list.yaml' - /provider/collections/{collection_id}/moderators/{moderator_id}/: - $ref: 'collection_provider/moderators_detail.yaml' + /provider/collections/{provider_id}/moderators/{moderator_id}/: + $ref: 'collection_providers/moderators_detail.yaml' From 3a87868dd23a07b4073f1ef4b8c9a7bee5562656 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Thu, 20 Mar 2025 09:29:49 -0400 Subject: [PATCH 12/21] add Identifier detail for top level route and add description text --- ...s.org_licenses_by-nc_4.0_legalcode.txt.pdf | Bin 72511 -> 0 bytes styles.css | 9 +++ swagger-spec/identifiers/definition.yaml | 35 +++++---- .../{detail.yaml => identifiers_detail.yaml} | 0 .../{list.yaml => identifiers_list.yaml} | 0 swagger-spec/nodes/identifiers_list.yaml | 73 +++++++++++++++++- swagger-spec/swagger.yaml | 27 ++++++- 7 files changed, 126 insertions(+), 18 deletions(-) delete mode 100644 creativecommons.org_licenses_by-nc_4.0_legalcode.txt.pdf create mode 100644 styles.css rename swagger-spec/identifiers/{detail.yaml => identifiers_detail.yaml} (100%) rename swagger-spec/identifiers/{list.yaml => identifiers_list.yaml} (100%) diff --git a/creativecommons.org_licenses_by-nc_4.0_legalcode.txt.pdf b/creativecommons.org_licenses_by-nc_4.0_legalcode.txt.pdf deleted file mode 100644 index 2fe850829906ba8e15506f83ccb08652303306f0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 72511 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

Uk+Whis0@@zqUQ9LG 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 List all identifiers associated with a given node. - #### Returns + ## Returns Returns a JSON object containing `data` and `links` keys. @@ -15,7 +15,7 @@ get: The `links` key contains a dictionary of links that can be used for [pagination](#tag/Pagination). - #### Filtering + ## Filtering You can optionally request that the response only include nodes that match your filters by utilizing the `filter` query parameter, e.g. @@ -80,3 +80,72 @@ get: meta: total: 2 per_page: 10 + +post: + summary: Create a New Identifier for a Node + description: >- + Create a new identifier for the specified node. + + #### Supported Identifiers + + Currently, only `doi` identifiers can be minted through this endpoint. + + #### Requirements + + - The user must have appropriate permissions (Admin or Write access) on the node. + - Nodes that are collections or folders cannot have identifiers minted. + + #### Example Request + + ```json + + { + "data": { + "type": "identifiers", + "attributes": { + "category": "doi" + } + } + } + + ``` + + operationId: nodes_identifiers_create + tags: + - Nodes + parameters: + - in: path + name: node_id + required: true + type: string + description: The unique identifier of the node. + + responses: + '201': + description: Identifier successfully created. + schema: + $ref: '../identifiers/definition.yaml' + examples: + application/json: + data: + type: identifiers + id: 57f1641db83f6901ed94b459 + attributes: + category: doi + value: 10.17605/OSF.IO/73PND + relationships: + referent: + links: + related: + href: https://api.osf.io/v2/nodes/73pnd/ + meta: {} + links: + self: https://api.osf.io/v2/identifiers/57f1641db83f6901ed94b459/ + '400': + description: Invalid request (e.g., DOI already exists or unsupported category). + '403': + description: You do not have permission to create identifiers on this node. + '404': + description: Node not found. + '503': + description: External identifier service unavailable. diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index e05951d..e7ca6d2 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -854,8 +854,23 @@ tags: adheres to the standards set for collection submissions. It aids in providing transparency and order to the process of managing collections and ensures that moderators and admins have the tools and information they need to effectively manage collection submissions. - - + - name: Identifiers + description: >- + Identifiers are unique strings associated with various entities in the OSF system, such as project nodes, + registrations or preprints. + Identifiers serve as a means to distinctly reference these entities using standardized formats like DOI + (Digital Object Identifier). Each identifier is linked to a specific entity, providing a persistent and + resolvable URL that can be used for citation, sharing, and retrieval purposes. + + Identifiers play a crucial role in ensuring that entities within the OSF ecosystem can be reliably accessed and + referenced across different platforms and services. By adhering to widely recognized standards, identifiers + facilitate interoperability and integration with external systems, enhancing the visibility and accessibility + of research outputs. + + The Identifiers system allows users to access both Datacite and Crossref for DOI minting services and stores + detailed metadata about each identifier, including its category, value, and the entity it is associated with. + This ensures that users can effectively manage and utilize identifiers in their research workflows, promoting + transparency and traceability of scholarly work. paths: @@ -1379,3 +1394,11 @@ paths: /provider/collections/{collection_id}/moderators/{moderator_id}/: $ref: 'collection_provider/moderators_detail.yaml' + + ###################### + # IDENTIFIERS # + ###################### + + /identifiers/{identifier_id}/: + $ref: 'identifiers/identifiers_detail.yaml' + From 777fc69c901269570c88430ca75265c57aa0f09a Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Thu, 20 Mar 2025 11:00:55 -0400 Subject: [PATCH 13/21] fix mistakes and typos --- swagger-spec/identifiers/definition.yaml | 1 - .../{identifiers_detail.yaml => detail.yaml} | 37 ++-- .../{identifiers_list.yaml => node_list.yaml} | 2 +- swagger-spec/nodes/identifiers_list.yaml | 177 +++++++++++------- swagger-spec/swagger.yaml | 8 +- 5 files changed, 133 insertions(+), 92 deletions(-) rename swagger-spec/identifiers/{identifiers_detail.yaml => detail.yaml} (52%) rename swagger-spec/identifiers/{identifiers_list.yaml => node_list.yaml} (98%) diff --git a/swagger-spec/identifiers/definition.yaml b/swagger-spec/identifiers/definition.yaml index e01561a..5bbcf12 100644 --- a/swagger-spec/identifiers/definition.yaml +++ b/swagger-spec/identifiers/definition.yaml @@ -54,4 +54,3 @@ properties: format: url readOnly: true description: 'URL to the detail page for this identifier.' - \ No newline at end of file diff --git a/swagger-spec/identifiers/identifiers_detail.yaml b/swagger-spec/identifiers/detail.yaml similarity index 52% rename from swagger-spec/identifiers/identifiers_detail.yaml rename to swagger-spec/identifiers/detail.yaml index 67be27f..07d06ae 100644 --- a/swagger-spec/identifiers/identifiers_detail.yaml +++ b/swagger-spec/identifiers/detail.yaml @@ -1,37 +1,45 @@ # /identifiers/{identifier_id}/ get: - summary: Retrieve an identifier + summary: Retrieve a Specific Identifier description: >- - Retrieves the details of an identifier + Retrieve the details of a specific identifier by its unique identifier ID. - #### Returns + Identifiers represent permanent references to OSF nodes, often registered with external services like DataCite + (for DOIs) or ARK registries. This endpoint provides information about the identifier’s category (e.g., DOI or ARK), + its value, and its association with the referent node. - Returns a JSON object with a `data` key containing the representation of the requested - identifier, if the request was successful. + #### Permissions - - 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. + - Public identifiers are accessible by any user. + - Private node identifiers require authentication and appropriate permissions (at least read access). parameters: - in: path + name: identifier_id type: string required: true - name: identifier_id - description: 'The unique id of the identifier.' + description: The unique identifier for the identifier resource. + tags: - Identifiers + operationId: identifiers_read + x-response-schema: Identifier + responses: '200': - description: 'OK' + description: Successful retrieval of the identifier. schema: $ref: definition.yaml examples: application/json: data: + id: 57f1641db83f6901ed94b45a + type: identifiers + attributes: + category: ark + value: c7605/osf.io/73pnd relationships: referent: links: @@ -40,8 +48,3 @@ get: meta: {} links: self: https://api.osf.io/v2/identifiers/57f1641db83f6901ed94b45a/ - attributes: - category: ark - value: c7605/osf.io/73pnd - type: identifiers - id: 57f1641db83f6901ed94b45a diff --git a/swagger-spec/identifiers/identifiers_list.yaml b/swagger-spec/identifiers/node_list.yaml similarity index 98% rename from swagger-spec/identifiers/identifiers_list.yaml rename to swagger-spec/identifiers/node_list.yaml index 3625ca4..2ef1567 100644 --- a/swagger-spec/identifiers/identifiers_list.yaml +++ b/swagger-spec/identifiers/node_list.yaml @@ -1,4 +1,4 @@ -# /identifiers/{node_id}/identifiers/ +# /identifiers/ get: summary: List all identifiers description: >- diff --git a/swagger-spec/nodes/identifiers_list.yaml b/swagger-spec/nodes/identifiers_list.yaml index 5fa83ea..b75c357 100644 --- a/swagger-spec/nodes/identifiers_list.yaml +++ b/swagger-spec/nodes/identifiers_list.yaml @@ -1,44 +1,55 @@ # /nodes/{node_id}/identifiers/ get: - summary: List all identifiers + summary: Retrieve Identifiers for a Node description: >- - List all identifiers associated with a given node. + Retrieve a list of all identifiers (such as DOIs or ARKs) associated with the specified node. - ## Returns + Identifiers are unique strings that reference the node in external systems. These can include + persistent identifiers such as DOIs (Digital Object Identifiers) or ARKs (Archival Resource Keys). - Returns a JSON object containing `data` and `links` keys. + #### Response Structure + The response returns a JSON object containing the following top-level keys: - The `data` key contains an array of identifiers. - Each resource in the array is a separate identifier object. + - `data`: An array of identifier resources. + - `links`: Pagination links (if applicable). + Each item in the `data` array is a distinct identifier object, containing details such as + the identifier `category` (e.g., `doi`, `ark`), its `value`, and links to the associated node. - The `links` key contains a dictionary of links that can be used for [pagination](#tag/Pagination). + #### Filtering - ## Filtering + You may filter the returned identifiers by category using the `filter[category]` query parameter. + **Example:** - You can optionally request that the response only include nodes that match your filters by utilizing the `filter` query parameter, e.g. - https://api.osf.io/v2/nodes/ezcuj/identifiers/?filter[category]=ark + Supported filter categories include: + - `doi` - Digital Object Identifier + - `ark` - Archival Resource Key + #### Permissions - Identifiers may be filtered by their `category` e.g `ark` or `doi`. + - This endpoint is public for nodes that are public. + - Authentication is required to access identifiers on private nodes, and the authenticated user must have read access. parameters: - - in: path name: node_id type: string required: true - description: 'The unique identifier of the node.' + description: The unique identifier of the node for which you want to retrieve associated identifiers. tags: - Nodes + - Identifiers + operationId: nodes_identifiers_list + x-response-schema: Identifier + responses: '200': - description: 'OK' + description: Successful retrieval of identifiers. schema: type: array items: @@ -46,59 +57,64 @@ get: examples: application/json: data: - - relationships: - referent: - links: - related: - href: https://api.osf.io/v2/nodes/73pnd/ - meta: {} - links: - self: https://api.osf.io/v2/identifiers/57f1641db83f6901ed94b459/ - attributes: - category: doi - value: 10.17605/OSF.IO/73PND - type: identifiers - id: 57f1641db83f6901ed94b459 - - relationships: - referent: - links: - related: - href: https://api.osf.io/v2/nodes/73pnd/ - meta: {} - links: - self: https://api.osf.io/v2/identifiers/57f1641db83f6901ed94b45a/ - attributes: - category: ark - value: c7605/osf.io/73pnd - type: identifiers - id: 57f1641db83f6901ed94b45a + - id: 57f1641db83f6901ed94b459 + type: identifiers + attributes: + category: doi + value: 10.17605/OSF.IO/73PND + relationships: + referent: + links: + related: + href: https://api.osf.io/v2/nodes/73pnd/ + meta: {} + links: + self: https://api.osf.io/v2/identifiers/57f1641db83f6901ed94b459/ + - id: 57f1641db83f6901ed94b45a + type: identifiers + attributes: + category: ark + value: c7605/osf.io/73pnd + relationships: + referent: + links: + related: + href: https://api.osf.io/v2/nodes/73pnd/ + meta: {} + links: + self: https://api.osf.io/v2/identifiers/57f1641db83f6901ed94b45a/ links: - first: - last: - prev: - next: + first: null + last: null + prev: null + next: null meta: total: 2 per_page: 10 post: - summary: Create a New Identifier for a Node + summary: Mint a New Identifier for a Node description: >- - Create a new identifier for the specified node. + Mint (create) a new identifier for the specified node. + + Currently, the OSF supports minting **DOI** identifiers through this endpoint. + Once created, identifiers are permanent and cannot be modified or deleted. - #### Supported Identifiers + #### Supported Identifier Categories - Currently, only `doi` identifiers can be minted through this endpoint. + - `doi`: Digital Object Identifier. #### Requirements - - The user must have appropriate permissions (Admin or Write access) on the node. - - Nodes that are collections or folders cannot have identifiers minted. + - You must have **Admin** or **Write** permissions on the node. + - The node must be **public** and must **not** be a collection or folder. + - Only nodes representing individual projects or components are eligible for DOI creation. + + #### Example Request Payload - #### Example Request ```json - + { "data": { "type": "identifiers", @@ -110,42 +126,59 @@ post: ``` + + #### Permissions + - Only authenticated users with the required permissions can mint new identifiers. + - This endpoint is does not authenticate for nodes that are private or not publicly available. + operationId: nodes_identifiers_create + tags: - Nodes + - Identifiers + parameters: - in: path name: node_id required: true type: string - description: The unique identifier of the node. + description: The unique identifier of the node for which you want to create an identifier. responses: '201': description: Identifier successfully created. schema: - $ref: '../identifiers/definition.yaml' + $ref: '../identifiers/definition.yaml' examples: application/json: data: - type: identifiers - id: 57f1641db83f6901ed94b459 - attributes: - category: doi - value: 10.17605/OSF.IO/73PND - relationships: - referent: - links: - related: - href: https://api.osf.io/v2/nodes/73pnd/ - meta: {} - links: - self: https://api.osf.io/v2/identifiers/57f1641db83f6901ed94b459/ + id: 57f1641db83f6901ed94b459 + type: identifiers + attributes: + category: doi + value: 10.17605/OSF.IO/73PND + relationships: + referent: + links: + related: + href: https://api.osf.io/v2/nodes/73pnd/ + meta: {} + links: + self: https://api.osf.io/v2/identifiers/57f1641db83f6901ed94b459/ + '400': - description: Invalid request (e.g., DOI already exists or unsupported category). + description: >- + Bad Request. Possible reasons include: + - The node already has a DOI identifier. + - The requested identifier category is not supported (only `doi` is allowed). + - The node is not eligible for DOI creation (e.g., it's a folder or collection). + '403': - description: You do not have permission to create identifiers on this node. + description: >- + Forbidden. You do not have permission to create identifiers on this node. + This may occur if: + - The node is private. + - You do not have Admin or Write access to the node. + '404': - description: Node not found. - '503': - description: External identifier service unavailable. + description: Node not found. Verify the node ID is correct and that you have permission to view the node. diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index e7ca6d2..ad1dd69 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -45,6 +45,7 @@ x-tagGroups: - Licenses - Logs - Institutions + - Identifiers - Registration Schemas - Registration Schema Blocks - Schema Responses @@ -1400,5 +1401,10 @@ paths: ###################### /identifiers/{identifier_id}/: - $ref: 'identifiers/identifiers_detail.yaml' + $ref: 'identifiers/detail.yaml' + + /identifiers/{node_id}/identifiers/: + $ref: 'identifiers/node_list.yaml' + + From 37f880e4fe7b4facc581fcc90b8f5e5cf236f563 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Mon, 24 Mar 2025 09:06:15 -0400 Subject: [PATCH 14/21] minor syntax and formatting changes --- swagger-spec/actions/definition.yaml | 48 ++--- .../actions/node_request_action_list.yaml | 79 +++----- .../actions/preprint_request_action_list.yaml | 156 ++++++--------- swagger-spec/actions/review_action_list.yaml | 189 +++++++----------- swagger-spec/region/region_detail.yaml | 9 +- swagger-spec/region/region_list.yaml | 4 +- swagger-spec/swagger.yaml | 34 ++-- 7 files changed, 213 insertions(+), 306 deletions(-) diff --git a/swagger-spec/actions/definition.yaml b/swagger-spec/actions/definition.yaml index e661656..4ca3f60 100644 --- a/swagger-spec/actions/definition.yaml +++ b/swagger-spec/actions/definition.yaml @@ -1,14 +1,3 @@ -description: >- - An Action represents a state transition, accompanied by an optional comment, on a reviewable object. - Actions are used to track moderation and request decisions on resources like Preprints, Registrations, - Node Requests, Schema Responses, and Collection Submissions. - - Each Action records who performed the action (the creator), the state change (`from_state` → `to_state`), - and the `trigger` event that initiated the change. Optional comments may provide additional context. - - Actions are typically created when moderators or administrators perform moderation or review workflows. - Some actions can be triggered automatically (`auto: true`), such as system transitions. - type: object required: - id @@ -23,8 +12,14 @@ properties: type: type: string - enum: [review-actions, node-request-actions, preprint-request-actions, registration-actions, schema-response-actions, collection-submission-actions] description: The type of action resource. + enum: + - review-actions + - node-request-actions + - preprint-request-actions + - registration-actions + - schema-response-actions + - collection-submission-actions example: review-actions attributes: @@ -38,27 +33,27 @@ properties: properties: trigger: type: string - description: >- + description: > The trigger that initiated the action. Triggers correspond to state changes in the workflow and may include submit, accept, reject, withdraw, etc. example: accept comment: type: string - description: >- + description: > Optional comment explaining the rationale for the action or providing additional details. - example: "This submission looks good to me." + example: This submission looks good to me. from_state: type: string - description: >- + description: > The state of the resource before the action was performed. This reflects the resource's state prior to the trigger being executed. example: pending to_state: type: string - description: >- + description: > The state of the resource after the action was performed. This reflects the resource's updated state as a result of the trigger. example: accepted @@ -77,15 +72,16 @@ properties: auto: type: boolean - description: >- - Indicates whether the action was automatically generated by the system (true), + description: > + Indicates whether the action was automatically generated by the system (true) or manually triggered by a user (false). example: false visible: type: boolean - description: >- - Indicates whether the action is visible to non-admin users (true) or only visible to admins and moderators (false). + description: > + Indicates whether the action is visible to non-admin users (true) + or only visible to admins and moderators (false). Visibility typically depends on the provider's review workflow and moderation settings. example: true @@ -96,8 +92,8 @@ properties: - target properties: creator: - description: The user who performed the action. type: object + description: The user who performed the action. properties: links: type: object @@ -123,8 +119,8 @@ properties: example: users target: - description: The resource (preprint, registration, node request, etc.) on which the action was performed. type: object + description: The resource (preprint, registration, node request, etc.) on which the action was performed. properties: links: type: object @@ -150,9 +146,9 @@ properties: example: preprints provider: - description: >- - The provider responsible for managing the review or moderation workflow for the target resource. type: object + description: > + The provider responsible for managing the review or moderation workflow for the target resource. properties: links: type: object @@ -184,4 +180,4 @@ properties: type: string format: uri description: The canonical API endpoint for this action. - example: 'https://api.osf.io/v2/actions/abc123/' + example: 'https://api.osf.io/v2/actions/abc123/' \ No newline at end of file diff --git a/swagger-spec/actions/node_request_action_list.yaml b/swagger-spec/actions/node_request_action_list.yaml index fd475db..e1404da 100644 --- a/swagger-spec/actions/node_request_action_list.yaml +++ b/swagger-spec/actions/node_request_action_list.yaml @@ -1,63 +1,37 @@ -# /actions/requests/nodes/: - +# /actions/requests/nodes/ post: summary: Create a Node Request Action - description: >- + description: > Create a new action on an existing Node Request. Node Request Actions represent state transitions or comments on node-related requests, such as access or withdrawal requests. Actions document and facilitate moderation workflows for node requests managed through the OSF. - ## Available Triggers + #### Available Triggers Supported triggers for Node Request Actions include: - - `submit`: Submit or resubmit the node request for review. No special permissions required. - - `accept`: Approve the node request. Requires admin permissions. - - `reject`: Reject the node request. Requires admin permissions. - - `edit_comment`: Add or update a comment without changing the request’s state. Requires admin permissions. - - #### Request Format - - This endpoint expects a JSON:API compliant payload structured as follows: - - ```json - { - "data": { - "type": "node-request-actions", - "attributes": { - "trigger": "accept", - "comment": "Approving the node access request." - }, - "relationships": { - "target": { - "data": { - "type": "node-requests", - "id": "nodeReq123" - } - } - } - } - } - ``` + - submit: Submit or resubmit the node request for review. No special permissions required. + - accept: Approve the node request. Requires admin permissions. + - reject: Reject the node request. Requires admin permissions. + - edit_comment: Add or update a comment without changing the request’s state. Requires admin permissions. #### Permissions Permission checks are enforced based on the trigger: - - Actions like `accept`, `reject`, and `edit_comment` require admin permissions on the target node. + - Actions like accept, reject, and edit_comment require admin permissions on the target node. #### Returns - On success, returns a `201 Created` response with a `data` object representing the newly created + On success, returns a 201 Created response with a data object representing the newly created Node Request Action. #### Errors Possible errors include: - - - `400 Bad Request`: Invalid payload or missing required fields. - - `403 Forbidden`: Insufficient permissions to perform the requested action. - - `409 Conflict`: The trigger is invalid for the node request’s current state. + - 400 Bad Request: Invalid payload or missing required fields. + - 403 Forbidden: Insufficient permissions to perform the requested action. + - 409 Conflict: The trigger is invalid for the node request’s current state. Refer to [Errors and Error Codes](#tag/Errors-and-Error-Codes) for more details. @@ -75,10 +49,11 @@ post: - in: body name: body required: true - description: >- - A JSON:API payload describing the Node Request Action to create. + description: A JSON:API compliant payload describing the Node Request Action to create. schema: type: object + required: + - data properties: data: type: object @@ -89,6 +64,8 @@ post: properties: type: type: string + enum: + - node-request-actions example: node-request-actions attributes: type: object @@ -97,10 +74,15 @@ post: properties: trigger: type: string + enum: + - submit + - accept + - reject + - edit_comment example: accept comment: type: string - example: "Approved node request." + example: Approving the node access request. relationships: type: object required: @@ -119,6 +101,8 @@ post: properties: type: type: string + enum: + - node-requests example: node-requests id: type: string @@ -128,7 +112,7 @@ post: '201': description: Node Request Action successfully created. schema: - type: object + $ref: 'definition.yaml' examples: application/json: data: @@ -136,7 +120,7 @@ post: type: node-request-actions attributes: trigger: accept - comment: "Approved node request." + comment: Approved node request. from_state: pending to_state: accepted date_created: '2024-03-13T15:30:00Z' @@ -164,13 +148,10 @@ post: self: 'https://api.osf.io/v2/actions/nodeAction123/' '400': - description: >- - Bad request. The payload is invalid or missing required fields. + description: Bad request. The payload is invalid or missing required fields. '403': - description: >- - Forbidden. You do not have permission to perform this action. + description: Forbidden. You do not have permission to perform this action. '409': - description: >- - Conflict. Invalid state transition for the given trigger. + description: Conflict. Invalid state transition for the given trigger. diff --git a/swagger-spec/actions/preprint_request_action_list.yaml b/swagger-spec/actions/preprint_request_action_list.yaml index b0b000c..ca0c8c3 100644 --- a/swagger-spec/actions/preprint_request_action_list.yaml +++ b/swagger-spec/actions/preprint_request_action_list.yaml @@ -1,7 +1,7 @@ # /actions/requests/preprints/: post: summary: Create a Preprint Request Action - description: >- + description: > Create a new action on an existing Preprint Request. Preprint Request Actions represent state changes or comments on preprint-related requests, @@ -19,9 +19,10 @@ post: #### Request Format - The request payload must follow the [JSON:API specification](https://jsonapi.org/), structured as: + The request payload must follow the JSON:API specification, structured as: ```json + { "data": { "type": "preprint-request-actions", @@ -38,34 +39,39 @@ post: } } } + } + ``` #### Returns - On success, returns a `201 Created` response with the newly created Preprint Request Action. + On success, returns a 201 Created response with the newly created Preprint Request Action. #### Errors - Errors return an `errors` object describing the failure: + Errors return an errors object describing the failure: - - `400 Bad Request`: Payload is invalid or missing required fields. - - `403 Forbidden`: Insufficient permissions to perform the action. - - `409 Conflict`: Invalid state transition. + - 400 Bad Request: Payload is invalid or missing required fields. + - 403 Forbidden: Insufficient permissions to perform the action. + - 409 Conflict: Invalid state transition. Refer to [Errors and Error Codes](#tag/Errors-and-Error-Codes) for more details. tags: - Actions + operationId: preprint_request_action_create + consumes: - application/json produces: - application/json + parameters: - in: body name: body required: true - description: A JSON:API representation of the Preprint Request Action to create. + description: A JSON:API compliant payload describing the Preprint Request Action to create. schema: type: object required: @@ -80,6 +86,8 @@ post: properties: type: type: string + enum: + - preprint-request-actions example: preprint-request-actions attributes: type: object @@ -88,6 +96,11 @@ post: properties: trigger: type: string + enum: + - submit + - accept + - reject + - edit_comment example: accept comment: type: string @@ -110,102 +123,57 @@ post: properties: type: type: string + enum: + - preprint-requests example: preprint-requests id: type: string example: preprintReq123 + responses: '201': description: Preprint Request Action successfully created. schema: - type: object - properties: + $ref: 'definition.yaml' + examples: + application/json: data: - type: object - properties: - id: - type: string - example: preprintAction123 - type: - type: string - example: preprint-request-actions - attributes: - type: object - properties: - trigger: - type: string - example: accept - comment: - type: string - example: "Approved preprint withdrawal request." - from_state: - type: string - example: pending - to_state: - type: string - example: accepted - date_created: - type: string - format: date-time - example: '2024-03-13T15:30:00Z' - date_modified: - type: string - format: date-time - example: '2024-03-13T15:30:00Z' - auto: - type: boolean - example: false - visible: - type: boolean - example: true - relationships: - type: object - properties: - creator: - type: object - properties: - links: - type: object - properties: - related: - type: string - example: 'https://api.osf.io/v2/users/user456/' - data: - type: object - properties: - id: - type: string - example: user456 - type: - type: string - example: users - target: - type: object - properties: - links: - type: object - properties: - related: - type: string - example: 'https://api.osf.io/v2/requests/preprints/preprintReq123/' - data: - type: object - properties: - id: - type: string - example: preprintReq123 - type: - type: string - example: preprint-requests - links: - type: object - properties: - self: - type: string - example: 'https://api.osf.io/v2/actions/preprintAction123/' + id: preprintAction123 + type: preprint-request-actions + attributes: + trigger: accept + comment: "Approved preprint withdrawal request." + from_state: pending + to_state: accepted + date_created: '2024-03-13T15:30:00Z' + date_modified: '2024-03-13T15:30:00Z' + auto: false + visible: true + relationships: + creator: + links: + related: + href: 'https://api.osf.io/v2/users/user456/' + meta: {} + data: + id: user456 + type: users + target: + links: + related: + href: 'https://api.osf.io/v2/requests/preprints/preprintReq123/' + meta: {} + data: + id: preprintReq123 + type: preprint-requests + links: + self: 'https://api.osf.io/v2/actions/preprintAction123/' + '400': description: Bad request. The request payload is invalid or incomplete. + '403': - description: Permission denied. + description: Permission denied. Insufficient permissions to perform the requested action. + '409': - description: Conflict due to invalid state transition. + description: Conflict due to an invalid state transition. diff --git a/swagger-spec/actions/review_action_list.yaml b/swagger-spec/actions/review_action_list.yaml index eadbb1e..e148e51 100644 --- a/swagger-spec/actions/review_action_list.yaml +++ b/swagger-spec/actions/review_action_list.yaml @@ -1,8 +1,7 @@ # /actions/reviews/: - get: summary: List Review Actions - description: >- + description: > Retrieve a list of review actions visible to the authenticated user. Review actions represent state transitions or comments made on reviewable objects, such as preprints. @@ -10,7 +9,15 @@ get: #### Filtering & Pagination - Supports pagination and filtering by `id`, `trigger`, `from_state`, `to_state`, `date_created`, and `date_modified`. + Supports pagination and filtering by the following fields: + - `id` + - `trigger` + - `from_state` + - `to_state` + - `date_created` + - `date_modified` + + Pagination follows the [JSON:API pagination specification](https://jsonapi.org/format/#fetching-pagination). #### Returns @@ -25,6 +32,49 @@ get: operationId: review_action_list produces: - application/json + + parameters: + - name: page + in: query + type: integer + description: Page number of the results to fetch. + required: false + - name: per_page + in: query + type: integer + description: Number of results per page. + required: false + - name: filter[id] + in: query + type: string + description: Filter by the unique ID of the review action. + required: false + - name: filter[trigger] + in: query + type: string + description: Filter by the trigger that initiated the action. + required: false + - name: filter[from_state] + in: query + type: string + description: Filter by the previous state of the resource. + required: false + - name: filter[to_state] + in: query + type: string + description: Filter by the new state of the resource. + required: false + - name: filter[date_created] + in: query + type: string + description: Filter by the creation date of the action. + required: false + - name: filter[date_modified] + in: query + type: string + description: Filter by the last modification date of the action. + required: false + responses: '200': description: Successful retrieval of review actions. @@ -34,129 +84,21 @@ get: data: type: array items: - type: object - properties: - id: - type: string - example: reviewAction123 - type: - type: string - example: review-actions - attributes: - type: object - properties: - trigger: - type: string - example: accept - comment: - type: string - example: "This looks great!" - from_state: - type: string - example: pending - to_state: - type: string - example: accepted - date_created: - type: string - format: date-time - example: '2024-03-14T10:00:00Z' - date_modified: - type: string - format: date-time - example: '2024-03-14T10:05:00Z' - auto: - type: boolean - example: false - visible: - type: boolean - example: true - relationships: - type: object - properties: - creator: - type: object - properties: - links: - type: object - properties: - related: - type: object - properties: - href: - type: string - format: uri - example: 'https://api.osf.io/v2/users/user456/' - meta: - type: object - data: - type: object - properties: - id: - type: string - example: user456 - type: - type: string - example: users - target: - type: object - properties: - links: - type: object - properties: - related: - type: object - properties: - href: - type: string - format: uri - example: 'https://api.osf.io/v2/preprints/xyz789/' - meta: - type: object - data: - type: object - properties: - id: - type: string - example: xyz789 - type: - type: string - example: preprints - provider: - type: object - properties: - links: - type: object - properties: - related: - type: object - properties: - href: - type: string - format: uri - example: 'https://api.osf.io/v2/providers/osf/' - meta: - type: object - data: - type: object - properties: - id: - type: string - example: osf - type: - type: string - example: providers + $ref: 'definition.yaml' meta: type: object properties: total: type: integer + description: Total number of actions available. example: 1 per_page: type: integer + description: Number of actions per page. example: 10 version: type: string + description: API version. example: '2.20' links: type: object @@ -164,4 +106,21 @@ get: self: type: string format: uri + description: Link to the current page of results. example: 'https://api.osf.io/v2/actions/reviews/' + next: + type: string + format: uri + description: Link to the next page of results. + example: 'https://api.osf.io/v2/actions/reviews/?page=2' + prev: + type: string + format: uri + description: Link to the previous page of results. + example: 'https://api.osf.io/v2/actions/reviews/?page=1' + + '400': + description: Bad request. Invalid filter or pagination parameters. + + '403': + description: Forbidden. The user does not have permission to view these review actions. diff --git a/swagger-spec/region/region_detail.yaml b/swagger-spec/region/region_detail.yaml index 984e6b1..06bebc9 100644 --- a/swagger-spec/region/region_detail.yaml +++ b/swagger-spec/region/region_detail.yaml @@ -7,12 +7,15 @@ get: A storage region defines the geographical or cloud-based location used by OSF Storage for storing files. - ## Returns - A JSON:API-compliant response containing a single `region` entity under the `data` key. + #### Returns + + A JSON:API-compliant response containing a single `region` entity under the `data` key. + + #### Errors - ## Errors Returns an `errors` object if unsuccessful: - `404 Not Found`: No region matches the provided `region_id`. + tags: - Regions operationId: region_detail diff --git a/swagger-spec/region/region_list.yaml b/swagger-spec/region/region_list.yaml index ef18b71..e1b26af 100644 --- a/swagger-spec/region/region_list.yaml +++ b/swagger-spec/region/region_list.yaml @@ -13,7 +13,9 @@ get: Supports standard pagination and sorting by name. ## Errors - If unsuccessful, returns an `errors` object. Refer to the [Errors and Error Codes](#tag/Errors-and-Error-Codes) section for details. + + If unsuccessful, returns an `errors` object. Refer to the [Errors and Error Codes](#tag/Errors-and-Error-Codes) section for details. + tags: - Regions operationId: region_list diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 286de67..248f128 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -131,8 +131,7 @@ tags: We have staging servers that will have newer features, including newer API features, that aren't ready for production. However, because those servers are subject to the whims of QA and whichever group needs to do specific testing, they aren't particular stable for API developers. - #### Testing Server - + The `test` subdomains of the OSF are intended to match, at any given time, the current production environment of the OSF. The test servers linked below are primarily for developing your API application on a stable system. @@ -154,8 +153,7 @@ tags: To use a Personal Access Token, make an `Authorization` header with the contents `Bearer ` as shown in the example below, replacing `` with your token. - curl -X "GET" "https://api.osf.io/v2/users/me/" \ - -H "Authorization: Bearer " + curl -X "GET" "https://api.osf.io/v2/users/me/" -H "Authorization: Bearer " To make a Personal Access Token, visit your OSF settings page (either on the [OSF](https://osf.io/settings/tokens) or our [testing server](https://test.osf.io/settings/tokens)) to create one. You can limit the scope of the token, but remember that it has access to all of the information that you do within the limits of the scope, so be careful with your tokens. @@ -164,10 +162,9 @@ tags: The OSF allows third-party web applications to connect to the OSF on behalf of other users via the OAuth 2.0 web application flow. - You can add a developer application from the OSF settings page (either on the [OSF](https://osf.io/settings/applications) or our [testing server](https://test.osf.io/settings/applications)). + You can add a developer application from the OSF settings page (either on the [OSF](https://osf.io/settings/applications) or our [testing server](https://osf.io/settings/applications)). - - We will be adding narrative documentation for handling OAuth flows, but for now, if you're familiar with OAuth, you can check out the [OAuth SSO Guide](https://github.com/CenterForOpenScience/osf-cas/blob/develop/README_OAUTH_SSO_GUIDE.md) for options. + You can check out the [OAuth SSO Guide](https://github.com/CenterForOpenScience/osf-cas/blob/develop/README_OAUTH_SSO_GUIDE.md) for options. - name: Pagination x-traitTag: true @@ -945,12 +942,15 @@ tags: Each region provides isolation of data in compliance with geographic or regulatory requirements. Users can specify their preferred region for storing project files when using OSF Storage. - **Attributes include:** + **Attributes include:** + + - `id`: Unique identifier of the region (e.g., `us-east-1`). - `name`: Human-readable name for the region (e.g., `US East`). **Endpoints include:** + - **List Regions:** Retrieve all available storage regions. - **Region Detail:** Retrieve details about a specific storage region. - name: Tokens @@ -978,13 +978,11 @@ tags: Scopes can be queried and managed through these endpoints to understand and control access levels associated with applications and tokens. - name: Actions description: >- - Actions represent state transitions or comments performed on reviewable or request-related resources within the OSF platform, such as Preprints, Nodes, Preprint Requests, Node Requests, and Collection Submissions. These endpoints document and facilitate moderation and administrative workflows, ensuring transparency and accountability in managing user interactions, moderation processes, and lifecycle management for various resources. - Each Action captures: - - **State transitions**: Tracking the movement of resources through different states (e.g., from pending to accepted). - **Comments** : Optional explanations or notes added during an action to provide context or reasons for state transitions. - **Triggers** : Specific actions (`submit`, `accept`, `reject`, `withdraw`, `edit_comment`, etc.) that initiate state transitions. - **Metadata** : Information such as timestamps for creation and modification, visibility settings, and whether the action was automated. + Actions represent state transitions or comments performed on reviewable or request-related resources within the + OSF platform, such as Preprints, Nodes, Preprint Requests, Node Requests, and Collection Submissions. + These endpoints document and facilitate moderation and administrative workflows, ensuring transparency and + accountability in managing user interactions, moderation processes, and lifecycle management for various + resources. Actions are categorized based on their targets: @@ -1002,9 +1000,9 @@ tags: - **type** : Type of action performed (e.g., `review-actions`, `node-request-actions`). - **attributes** : Information including `trigger`, `comment`, `from_state`, `to_state`, timestamps (`date_created`, `date_modified`), visibility (`visible`), and automation flag (`auto`). - **relationships** : - - `creator`: User who initiated the action. - - **target** : The resource the action applies to (e.g., Preprint, Node Request). - - **provider** : Provider associated with the target, if applicable. + - `creator`: User who initiated the action. + - `target` : The resource the action applies to (e.g., Preprint, Node Request). + - `provider` : Provider associated with the target, if applicable. Actions may fail due to various reasons, resulting in standard error responses: - `400 Bad Request`: Invalid or malformed payload. From 65c748513c89c6a00aa33e808a76bdfab1bac187 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Mon, 24 Mar 2025 14:15:16 -0400 Subject: [PATCH 15/21] fix preprint provider issues --- .../moderator_definition.yaml | 98 +++++++++++++++++++ .../preprint_providers/moderators_detail.yaml | 2 +- .../preprint_providers/moderators_list.yaml | 18 ++-- .../provider_moderator_detail.yaml | 25 ++--- .../provider_moderator_list.yaml | 20 ++-- 5 files changed, 131 insertions(+), 32 deletions(-) create mode 100644 swagger-spec/preprint_providers/moderator_definition.yaml diff --git a/swagger-spec/preprint_providers/moderator_definition.yaml b/swagger-spec/preprint_providers/moderator_definition.yaml new file mode 100644 index 0000000..b5828f0 --- /dev/null +++ b/swagger-spec/preprint_providers/moderator_definition.yaml @@ -0,0 +1,98 @@ +type: object +description: A moderator for a preprint provider. +required: + - id + - type + - attributes + - relationships + - links +properties: + id: + type: string + description: The unique identifier of the moderator. + example: moderator_1 + type: + type: string + enum: + - moderators + description: Must be 'moderators'. + example: moderators + attributes: + type: object + required: + - full_name + - email + - permission_group + - date_added + properties: + full_name: + type: string + description: Full name of the moderator. + example: Ada Lovelace + email: + type: string + format: email + description: Email address of the moderator. + example: ada.lovelace@example.com + permission_group: + type: string + enum: + - moderator + - admin + description: | + The permission group for the moderator. + - `moderator`: Can review and moderate preprint submissions. + - `admin`: Can manage submissions and other moderators. + example: admin + date_added: + type: string + format: date-time + description: The date the moderator was added to the provider. + example: '2024-01-15T12:34:56Z' + relationships: + type: object + properties: + preprint_provider: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - preprint_providers + description: Must be 'preprint_providers'. + example: preprint_providers + id: + type: string + description: The unique identifier of the preprint provider. + example: provider_1 + links: + type: object + properties: + self: + type: string + format: uri + description: A link to this moderator resource. + example: https://api.test.osf.io/v2/preprint_providers/provider_1/moderators/moderator_1/ +example: + id: moderator_1 + type: moderators + attributes: + full_name: Ada Lovelace + email: ada.lovelace@example.com + permission_group: admin + date_added: '2024-01-15T12:34:56Z' + relationships: + preprint_provider: + data: + type: preprint_providers + id: provider_1 + links: + self: https://api.test.osf.io/v2/preprint_providers/provider_1/moderators/moderator_1/ diff --git a/swagger-spec/preprint_providers/moderators_detail.yaml b/swagger-spec/preprint_providers/moderators_detail.yaml index 56cda99..99649ac 100644 --- a/swagger-spec/preprint_providers/moderators_detail.yaml +++ b/swagger-spec/preprint_providers/moderators_detail.yaml @@ -34,7 +34,7 @@ get: '200': description: Successful retrieval of the moderator details. schema: - $ref: 'definition.yaml' + $ref: 'moderator_definition.yaml' examples: application/json: data: diff --git a/swagger-spec/preprint_providers/moderators_list.yaml b/swagger-spec/preprint_providers/moderators_list.yaml index 5e6948c..a331601 100644 --- a/swagger-spec/preprint_providers/moderators_list.yaml +++ b/swagger-spec/preprint_providers/moderators_list.yaml @@ -5,12 +5,12 @@ get: description: >- Retrieve a list of moderators for a specific preprint provider, including their assigned roles and user information. - #### Permissions - - The authenticated user must be an administrator of the preprint provider. + ## Permissions + - The authenticated user must be an administrator of the preprint provider. - #### Returns - - A JSON object with a `data` key containing a list of moderators. - - Each moderator includes user details and their assigned permission group. + ## Returns + - A JSON object with a `data` key containing a list of moderators. + - Each moderator includes user details and their assigned permission group. tags: - Preprint Providers @@ -33,7 +33,7 @@ get: data: type: array items: - $ref: 'definition.yaml' + $ref: 'moderator_definition.yaml' example: data: - id: "moderator_1" @@ -79,10 +79,10 @@ post: description: >- Add a new moderator to the preprint provider by specifying the user and their permission group. - #### Permissions - - The authenticated user must be an administrator of the preprint provider. + ## Permissions + - The authenticated user must be an administrator of the preprint provider. - #### Request Body + ## Request Body Provide the `user_id` and `permission_group` in the `attributes` object to create a new moderator assignment. Available values for `permission_group` are: - `moderator`: Can review and moderate preprint submissions. diff --git a/swagger-spec/preprint_providers/provider_moderator_detail.yaml b/swagger-spec/preprint_providers/provider_moderator_detail.yaml index 1e1a004..fc2a1d6 100644 --- a/swagger-spec/preprint_providers/provider_moderator_detail.yaml +++ b/swagger-spec/preprint_providers/provider_moderator_detail.yaml @@ -34,7 +34,7 @@ get: '200': description: Successful retrieval of the moderator. schema: - $ref: 'definition.yaml' + $ref: 'moderator_definition.yaml' examples: application/json: data: @@ -66,18 +66,19 @@ patch: description: >- Update the permission group for a specific moderator on a preprint provider. - #### Permissions + ## Permissions - The authenticated user must be an administrator of the preprint provider. - #### Request Body + ## Request Body + Provide the `permission_group` attribute in the `attributes` object to update the moderator. Available values for `permission_group` are: - `moderator`: Can review and moderate preprint submissions. - `admin`: Can manage submissions and other moderators. - #### Returns - - A JSON object with the updated moderator details under the `data` key if the update is successful. - - If unsuccessful, returns an `errors` object detailing the validation issues. + ## Returns + - A JSON object with the updated moderator details under the `data` key if the update is successful. + - If unsuccessful, returns an `errors` object detailing the validation issues. tags: - Preprint Providers @@ -144,7 +145,7 @@ patch: '200': description: Moderator successfully updated. schema: - $ref: 'definition.yaml' + $ref: 'moderator_definition.yaml' examples: application/json: data: @@ -178,12 +179,12 @@ delete: description: >- Remove a moderator from a preprint provider. - #### Permissions - - The authenticated user must be an administrator of the preprint provider. + ## Permissions + - The authenticated user must be an administrator of the preprint provider. - #### Returns - - Returns a `204 No Content` response if the deletion is successful. - - If unsuccessful, returns an `errors` object detailing the issue. + ## Returns + - Returns a `204 No Content` response if the deletion is successful. + - If unsuccessful, returns an `errors` object detailing the issue. tags: - Preprint Providers diff --git a/swagger-spec/preprint_providers/provider_moderator_list.yaml b/swagger-spec/preprint_providers/provider_moderator_list.yaml index 9c889dd..56bd4c6 100644 --- a/swagger-spec/preprint_providers/provider_moderator_list.yaml +++ b/swagger-spec/preprint_providers/provider_moderator_list.yaml @@ -5,12 +5,12 @@ get: description: >- Retrieve a list of all moderators assigned to a specific preprint provider. - #### Permissions - - The authenticated user must be an administrator of the preprint provider. + ## Permissions + - The authenticated user must be an administrator of the preprint provider. - #### Returns - - A JSON object with a `data` key containing an array of moderator records. - - Each moderator includes their permission group and basic user information. + ## Returns + - A JSON object with a `data` key containing an array of moderator records. + - Each moderator includes their permission group and basic user information. tags: - Preprint Providers @@ -114,15 +114,15 @@ post: description: >- Add a new moderator to the specified preprint provider. - #### Permissions - - The authenticated user must be an administrator of the preprint provider. + ## Permissions + - The authenticated user must be an administrator of the preprint provider. - #### Request Body + ## Request Body Provide the `permission_group` and the `user_id` for the moderator in the `relationships` object. #### Returns - - A JSON object with the newly created moderator details under the `data` key if successful. - - If unsuccessful, returns an `errors` object detailing the validation issues. + - A JSON object with the newly created moderator details under the `data` key if successful. + - If unsuccessful, returns an `errors` object detailing the validation issues. tags: - Preprint Providers From 6261868f15edf69ea6e30f9ea846a4ded29771e7 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Mon, 24 Mar 2025 16:06:54 -0400 Subject: [PATCH 16/21] fix missing provider routes and definations --- .../{licenses.yaml => licenses_list.yaml} | 0 ...provider_taxonomies_highlighted_list.yaml} | 29 +- .../provider_taxonomies_list.yaml | 49 +- ...submissions.yaml => submissions_list.yaml} | 0 .../collection_submissions/definition.yaml | 69 +++ .../registration_action/definition.yaml | 122 ++++ ...on_actions_list.yaml => actions_list.yaml} | 2 +- .../registration_providers/definition.yaml | 182 ++++++ .../registration_providers/detail.yaml | 127 ++++ .../registration_providers/licenses_list.yaml | 567 ++++++++++++++++++ swagger-spec/registration_providers/list.yaml | 82 +++ ...provider_taxonomies_highlighted_list.yaml} | 0 .../registrations_list.yaml | 2 +- .../registrations_schema_list.yaml | 132 ---- ..._requests_list.yaml => requests_list.yaml} | 5 +- .../registration_providers/schemas_list.yaml | 115 ++++ ..._subjects_list.yaml => subjects_list.yaml} | 0 ...ssions_list.yaml => submissions_list.yaml} | 23 +- .../registration_request/definition.yaml | 94 +++ swagger-spec/swagger.yaml | 83 ++- 20 files changed, 1503 insertions(+), 180 deletions(-) rename swagger-spec/collection_providers/{licenses.yaml => licenses_list.yaml} (100%) rename swagger-spec/collection_providers/{provider_taxonomies_highlitghted_list.yaml => provider_taxonomies_highlighted_list.yaml} (69%) rename swagger-spec/collection_providers/{submissions.yaml => submissions_list.yaml} (100%) create mode 100644 swagger-spec/collection_submissions/definition.yaml create mode 100644 swagger-spec/registration_action/definition.yaml rename swagger-spec/registration_providers/{registration_actions_list.yaml => actions_list.yaml} (98%) create mode 100644 swagger-spec/registration_providers/definition.yaml create mode 100644 swagger-spec/registration_providers/detail.yaml create mode 100644 swagger-spec/registration_providers/licenses_list.yaml create mode 100644 swagger-spec/registration_providers/list.yaml rename swagger-spec/registration_providers/{provider_taxonomies_highlitghted_list.yaml => provider_taxonomies_highlighted_list.yaml} (100%) delete mode 100644 swagger-spec/registration_providers/registrations_schema_list.yaml rename swagger-spec/registration_providers/{registration_requests_list.yaml => requests_list.yaml} (97%) create mode 100644 swagger-spec/registration_providers/schemas_list.yaml rename swagger-spec/registration_providers/{registrations_subjects_list.yaml => subjects_list.yaml} (100%) rename swagger-spec/registration_providers/{registrations_submissions_list.yaml => submissions_list.yaml} (95%) create mode 100644 swagger-spec/registration_request/definition.yaml diff --git a/swagger-spec/collection_providers/licenses.yaml b/swagger-spec/collection_providers/licenses_list.yaml similarity index 100% rename from swagger-spec/collection_providers/licenses.yaml rename to swagger-spec/collection_providers/licenses_list.yaml diff --git a/swagger-spec/collection_providers/provider_taxonomies_highlitghted_list.yaml b/swagger-spec/collection_providers/provider_taxonomies_highlighted_list.yaml similarity index 69% rename from swagger-spec/collection_providers/provider_taxonomies_highlitghted_list.yaml rename to swagger-spec/collection_providers/provider_taxonomies_highlighted_list.yaml index 988f4ee..7bcd638 100644 --- a/swagger-spec/collection_providers/provider_taxonomies_highlitghted_list.yaml +++ b/swagger-spec/collection_providers/provider_taxonomies_highlighted_list.yaml @@ -3,7 +3,7 @@ get: summary: List Highlighted Taxonomies for a Collection Provider (Deprecated) description: | Retrieve the list of highlighted taxonomies for a Collection Provider. - + **Deprecated:** Use the `highlighted subjects` endpoint instead. deprecated: true @@ -12,8 +12,7 @@ get: - in: path name: provider_id required: true - schema: - type: string + type: string description: The unique ID of the collection provider. tags: @@ -22,15 +21,21 @@ get: responses: '200': description: A list of highlighted taxonomies. - content: - application/vnd.api+json: - example: - data: - - id: "xyz-highlighted" - type: "taxonomies" - attributes: - text: "Open Science" - parents: [] + schema: + type: object + properties: + data: + type: array + items: + $ref: '../taxonomies/definition.yaml' + examples: + application/json: + data: + - id: "xyz-highlighted" + type: "taxonomies" + attributes: + text: "Open Science" + parents: [] '401': description: Authentication credentials were not provided or are invalid. diff --git a/swagger-spec/collection_providers/provider_taxonomies_list.yaml b/swagger-spec/collection_providers/provider_taxonomies_list.yaml index f9ae302..846b3db 100644 --- a/swagger-spec/collection_providers/provider_taxonomies_list.yaml +++ b/swagger-spec/collection_providers/provider_taxonomies_list.yaml @@ -3,44 +3,55 @@ get: summary: List Taxonomies for a Collection Provider (Deprecated) description: | Retrieve the full taxonomy for a specific Collection Provider. - + **Deprecated:** Use `subjects` endpoints instead. deprecated: true + produces: + - application/vnd.api+json + + tags: + - Collection Providers + parameters: - in: path name: provider_id required: true - schema: - type: string + type: string description: The unique ID of the collection provider. - tags: - - Collection Providers - responses: '200': description: A list of taxonomies. - content: + schema: + type: object + properties: + data: + type: array + items: + $ref: '../taxonomies/definition.yaml' + examples: application/vnd.api+json: - example: - data: - - id: "abc-subject" - type: "taxonomies" - attributes: - text: "Psychology" - parents: [] - - id: "def-subject" - type: "taxonomies" - attributes: - text: "Cognitive Psychology" - parents: ["abc-subject"] + data: + - id: "abc-subject" + type: "taxonomies" + attributes: + text: "Psychology" + parents: [] + - id: "def-subject" + type: "taxonomies" + attributes: + text: "Cognitive Psychology" + parents: + - abc-subject '401': description: Authentication credentials were not provided or are invalid. + '403': description: You do not have permission to view taxonomies for this provider. + '404': description: Collection provider not found. diff --git a/swagger-spec/collection_providers/submissions.yaml b/swagger-spec/collection_providers/submissions_list.yaml similarity index 100% rename from swagger-spec/collection_providers/submissions.yaml rename to swagger-spec/collection_providers/submissions_list.yaml diff --git a/swagger-spec/collection_submissions/definition.yaml b/swagger-spec/collection_submissions/definition.yaml new file mode 100644 index 0000000..6ae3a55 --- /dev/null +++ b/swagger-spec/collection_submissions/definition.yaml @@ -0,0 +1,69 @@ +type: object +required: + - id + - type + - attributes + - relationships + - links +properties: + id: + type: string + example: sub1 + type: + type: string + example: collection-submissions + attributes: + type: object + required: + - state + - date_submitted + properties: + state: + type: string + enum: + - in_progress + - pending + - accepted + - rejected + - removed + example: pending + date_submitted: + type: string + format: date-time + example: '2024-12-01T12:00:00Z' + relationships: + type: object + required: + - collection + - creator + properties: + collection: + type: object + properties: + data: + type: object + properties: + type: + type: string + example: collections + id: + type: string + example: col123 + creator: + type: object + properties: + data: + type: object + properties: + type: + type: string + example: users + id: + type: string + example: user456 + links: + type: object + properties: + self: + type: string + example: "https://api.test.osf.io/v2/collection_submissions/sub1/" diff --git a/swagger-spec/registration_action/definition.yaml b/swagger-spec/registration_action/definition.yaml new file mode 100644 index 0000000..638c6df --- /dev/null +++ b/swagger-spec/registration_action/definition.yaml @@ -0,0 +1,122 @@ +type: object +required: + - id + - type + - attributes + - relationships + - links + +properties: + id: + type: string + description: Unique identifier for the registration action. + example: ract1 + + type: + type: string + description: The type of this resource; always `registration_action`. + example: registration_action + + attributes: + type: object + required: + - trigger + - from_state + - to_state + - date_created + properties: + trigger: + type: string + description: > + The trigger event that caused the action. + Examples include: `submit`, `accept`, `reject`, `edit_comment`, etc. + example: submit + + comment: + type: string + description: Optional comment explaining the reason or context for the action. + example: "Initial submission" + + from_state: + type: string + description: > + The state of the registration before the action was performed. + example: draft + + to_state: + type: string + description: > + The state of the registration after the action was performed. + example: unapproved + + date_created: + type: string + format: date-time + description: Timestamp indicating when the action was performed. + example: "2024-05-01T12:00:00Z" + + date_modified: + type: string + format: date-time + description: Timestamp indicating when the action was last modified (if applicable). + example: "2024-05-01T12:00:00Z" + + auto: + type: boolean + description: Indicates if the action was automatically triggered by the system. + example: false + + visible: + type: boolean + description: Indicates whether the action is visible to non-admin users. + example: true + + relationships: + type: object + required: + - creator + - target + properties: + creator: + type: object + description: The user who performed the action. + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + example: user123 + type: + type: string + example: users + + target: + type: object + description: The registration this action applies to. + properties: + data: + type: object + required: + - id + - type + properties: + id: + type: string + example: reg1 + type: + type: string + example: registrations + + links: + type: object + description: Links related to this registration action. + properties: + self: + type: string + format: uri + description: The API URL to access this action directly. + example: "https://api.test.osf.io/v2/registrations/reg1/actions/ract1/" \ No newline at end of file diff --git a/swagger-spec/registration_providers/registration_actions_list.yaml b/swagger-spec/registration_providers/actions_list.yaml similarity index 98% rename from swagger-spec/registration_providers/registration_actions_list.yaml rename to swagger-spec/registration_providers/actions_list.yaml index 50345f0..e9fa6d0 100644 --- a/swagger-spec/registration_providers/registration_actions_list.yaml +++ b/swagger-spec/registration_providers/actions_list.yaml @@ -49,7 +49,7 @@ get: data: type: array items: - $ref: './definition.yaml' + $ref: '../registration_action/definition.yaml' links: type: object properties: diff --git a/swagger-spec/registration_providers/definition.yaml b/swagger-spec/registration_providers/definition.yaml new file mode 100644 index 0000000..708e6b0 --- /dev/null +++ b/swagger-spec/registration_providers/definition.yaml @@ -0,0 +1,182 @@ +type: object +required: + - id + - type + - attributes + - relationships + - links + +properties: + id: + type: string + description: The unique identifier of the Registration Provider. + example: osf + + type: + type: string + description: The type of resource; always `registration_providers`. + example: registration_providers + + attributes: + type: object + required: + - name + - description + - domain + - subjects_acceptable + properties: + name: + type: string + description: The name of the registration provider. + example: Open Science Framework + + description: + type: string + description: A short description of the provider. + example: A scholarly commons to connect the entire research cycle. + + domain: + type: string + description: The domain associated with the registration provider. + example: osf.io + + banner_path: + type: string + description: The path to the banner image displayed for the provider. + example: /static/img/registration_providers/cos-logo.png + + logo_path: + type: string + description: The path to the logo image for the provider. + example: /static/img/registration_providers/cos-logo.png + + header_text: + type: string + description: Optional custom text for the provider's header. + example: '' + + social_twitter: + type: string + description: Twitter handle or link for the provider. + example: '' + + social_facebook: + type: string + description: Facebook handle or link for the provider. + example: '' + + social_instagram: + type: string + description: Instagram handle or link for the provider. + example: '' + + email_support: + type: string + description: Email address for technical support inquiries. + example: '' + + email_contact: + type: string + description: Email address for general contact. + example: '' + + advisory_board: + type: string + description: Details about the provider's advisory board (if any). + example: '' + + example: + type: string + description: Example metadata related to the provider. + example: khbvy + + subjects_acceptable: + type: array + description: > + An array describing the subjects acceptable to this provider. + This array consists of nested subject hierarchies with booleans indicating whether all child subjects are included. + example: + - - - "584240d954be81056ceca9e5" # Parent subject ID (Architecture) + - "584240da54be81056cecac87" # Child subject ID (Architectural Engineering) + - true + - - - "584240da54be81056cecaca9" # Parent subject ID (Engineering) + - "584240db54be81056cecacd6" # Child subject ID (Aerospace Engineering) + - "584240da54be81056cecaa74" # Grandchild subject ID (Aerodynamics and Fluid Mechanics) + - false + + relationships: + type: object + description: Related resources associated with this registration provider. + properties: + licenses_acceptable: + type: object + description: Licenses accepted by this provider. + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: https://api.osf.io/v2/registration_providers/osf/licenses/ + meta: + type: object + + taxonomies: + type: object + description: Taxonomies (subjects) available for this provider. + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: https://api.osf.io/v2/registration_providers/osf/taxonomies/ + meta: + type: object + + registrations: + type: object + description: Registrations managed by this provider. + properties: + links: + type: object + properties: + related: + type: object + properties: + href: + type: string + format: uri + example: https://api.osf.io/v2/registration_providers/osf/registrations/ + meta: + type: object + + links: + type: object + description: Links to useful URLs for the registration provider. + properties: + self: + type: string + format: uri + description: The canonical API endpoint for this provider. + example: https://api.osf.io/v2/registration_providers/osf/ + + registrations: + type: string + format: uri + description: Link to the registrations list for this provider. + example: https://api.osf.io/v2/registration_providers/osf/registrations/ + + external_url: + type: string + format: uri + description: External website for this provider. + example: https://osf.io/registrations/ diff --git a/swagger-spec/registration_providers/detail.yaml b/swagger-spec/registration_providers/detail.yaml new file mode 100644 index 0000000..0febf1a --- /dev/null +++ b/swagger-spec/registration_providers/detail.yaml @@ -0,0 +1,127 @@ +get: + summary: Retrieve a Registration Provider + description: >- + Retrieves the details of a Registration Provider. + + #### Returns + + Returns a JSON object with a `data` key containing the representation of the requested + Registration Provider, if the request is successful. + + + 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. + + + #### Acceptable Subjects Structure + + Each Registration Provider specifies acceptable subjects. + + `subjects_acceptable` is an array found in `attributes`. + + Subjects consist of general parent subjects (e.g., Engineering), + more specific child subjects (e.g., Aerospace Engineering), + and even more specific grandchild subjects (e.g., Aerodynamics and Fluid Mechanics). + Subjects can only be nested 3 deep. + + + "subjects_acceptable": [ + [ + [ + # Parent Subject: + # Architecture + "584240d954be81056ceca9e5", + + # Child Subject: + # Architectural Engineering + "584240da54be81056cecac87" + ], + # Include all Architectural Engineering's children: + true + ], + [ + [ + # Parent Subject: + # Engineering + "584240da54be81056cecaca9", + + # Child Subject: + # Aerospace Engineering + "584240db54be81056cecacd6", + + # Grandchild Subject: + # Aerodynamics and Fluid Mechanics + "584240da54be81056cecaa74" + ], + # All nestings 3 deep must be false + false + ] + ] + + The above structure would allow Architecture, Architectural Engineering, all of Architectural Engineering's children, + Engineering, Aerospace Engineering, and Aerodynamics and Fluid Mechanics. + + parameters: + - in: path + type: string + required: true + name: provider_id + description: 'The unique identifier of the Registration Provider.' + tags: + - Registration Providers + operationId: registration_provider_detail + x-response-schema: 'Registration Provider' + responses: + '200': + description: 'OK' + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + relationships: + licenses_acceptable: + links: + related: + href: https://api.osf.io/v2/registration_providers/osf/licenses/ + meta: {} + taxonomies: + links: + related: + href: https://api.osf.io/v2/registration_providers/osf/taxonomies/ + meta: {} + registrations: + links: + related: + href: https://api.osf.io/v2/registration_providers/osf/registrations/ + meta: {} + links: + self: https://api.osf.io/v2/registration_providers/osf/ + registrations: https://api.osf.io/v2/registration_providers/osf/registrations/ + external_url: https://osf.io/registrations/ + attributes: + social_instagram: '' + advisory_board: '' + email_support: '' + banner_path: "/static/img/registration_providers/cos-logo.png" + logo_path: "/static/img/registration_providers/cos-logo.png" + subjects_acceptable: [] + description: A scholarly commons to connect the entire research cycle + social_facebook: '' + header_text: '' + social_twitter: '' + email_contact: '' + example: khbvy + name: Open Science Framework + domain: 'osf.io' + type: preprint_providers + id: osf + links: + first: null + last: null + prev: null + next: null + meta: + total: 5 + per_page: 10 diff --git a/swagger-spec/registration_providers/licenses_list.yaml b/swagger-spec/registration_providers/licenses_list.yaml new file mode 100644 index 0000000..2e7c8a6 --- /dev/null +++ b/swagger-spec/registration_providers/licenses_list.yaml @@ -0,0 +1,567 @@ +# /providers/registations/{provider_id}/licenses/ +get: + summary: Registration Providers Licenses List + description: >- + + This returns the lists of possible licenses for a Registration. + + #### Permissions + + This information is public. + + #### Returns + + Returns a JSON object containing `data` and `links` keys. + + The `data` key contains an array of license ids. + + The `links` key contains a dictionary of links that can be used for [pagination](#tag/Pagination). + parameters: + - in: path + type: string + required: true + name: provider_id + description: 'A short id for that Registration' + tags: + - Registration Providers + operationId: registration_provider_detail + x-response-schema: Registration Provider + consumes: + - application/json + responses: + '200': + description: 'OK' + examples: + application/json: + data: + - id: 5c252c8e0989e100220edb73 + type: licenses + attributes: + name: CC-By Attribution 4.0 International + text: | + Creative Commons Attribution 4.0 International Public License + + By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. + + Section 1 – Definitions. + + Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. + Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. + Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. + Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. + Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. + Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License. + Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. + Licensor means the individual(s) or entity(ies) granting rights under this Public License. + Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. + Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. + You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. + Section 2 – Scope. + + License grant. + Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: + reproduce and Share the Licensed Material, in whole or in part; and + produce, reproduce, and Share Adapted Material. + Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. + Term. The term of this Public License is specified in Section 6(a). + Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. + Downstream recipients. + Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. + No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. + No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). + Other rights. + + Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. + Patent and trademark rights are not licensed under this Public License. + To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. + Section 3 – License Conditions. + + Your exercise of the Licensed Rights is expressly made subject to the following conditions. + + Attribution. + + If You Share the Licensed Material (including in modified form), You must: + + retain the following if it is supplied by the Licensor with the Licensed Material: + identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); + a copyright notice; + a notice that refers to this Public License; + a notice that refers to the disclaimer of warranties; + a URI or hyperlink to the Licensed Material to the extent reasonably practicable; + indicate if You modified the Licensed Material and retain an indication of any previous modifications; and + indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. + You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. + If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. + If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License. + Section 4 – Sui Generis Database Rights. + + Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: + + for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; + if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and + You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. + For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. + Section 5 – Disclaimer of Warranties and Limitation of Liability. + + Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You. + To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You. + The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. + Section 6 – Term and Termination. + + This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. + Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: + + automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + upon express reinstatement by the Licensor. + For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. + For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. + Sections 1, 5, 6, 7, and 8 survive termination of this Public License. + Section 7 – Other Terms and Conditions. + + The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. + Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. + Section 8 – Interpretation. + + For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. + To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. + No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. + Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. + url: https://creativecommons.org/licenses/by/4.0/legalcode + required_fields: [] + links: + self: https://api.staging.osf.io/v2/licenses/5c252c8e0989e100220edb73/ + - id: 5c252c8e0989e100220edb74 + type: licenses + attributes: + name: Artistic License 2.0 + text: "\t\t The Artistic License 2.0\n\n\t Copyright (c) 2000-2006, The + Perl Foundation.\n\n Everyone is permitted to copy and distribute verbatim + copies\n of this license document, but changing it is not allowed.\n\nPreamble\n\nThis + license establishes the terms under which a given free software\nPackage may + be copied, modified, distributed, and/or redistributed.\nThe intent is that + the Copyright Holder maintains some artistic\ncontrol over the development of + that Package while still keeping the\nPackage available as open source and free + software.\n\nYou are always permitted to make arrangements wholly outside of + this\nlicense directly with the Copyright Holder of a given Package. If the\nterms + of this license do not permit the full use that you propose to\nmake of the + Package, you should contact the Copyright Holder and seek\na different licensing + arrangement. \n\nDefinitions\n\n \"Copyright Holder\" means the individual(s) + or organization(s)\n named in the copyright notice for the entire Package.\n\n + \ \"Contributor\" means any party that has contributed code or other\n material + to the Package, in accordance with the Copyright Holder's\n procedures.\n\n + \ \"You\" and \"your\" means any person who would like to copy,\n distribute, + or modify the Package.\n\n \"Package\" means the collection of files distributed + by the\n Copyright Holder, and derivatives of that collection and/or of\n + \ those files. A given Package may consist of either the Standard\n Version, + or a Modified Version.\n\n \"Distribute\" means providing a copy of the Package + or making it\n accessible to anyone else, or in the case of a company or\n + \ organization, to others outside of your company or organization.\n\n \"Distributor + Fee\" means any fee that you charge for Distributing\n this Package or providing + support for this Package to another\n party. It does not mean licensing + fees.\n\n \"Standard Version\" refers to the Package if it has not been\n + \ modified, or has been modified only in ways explicitly requested\n by + the Copyright Holder.\n\n \"Modified Version\" means the Package, if it has + been changed, and\n such changes were not explicitly requested by the Copyright\n + \ Holder. \n\n \"Original License\" means this Artistic License as Distributed + with\n the Standard Version of the Package, in its current version or as\n + \ it may be modified by The Perl Foundation in the future.\n\n \"Source\" + form means the source code, documentation source, and\n configuration files + for the Package.\n\n \"Compiled\" form means the compiled bytecode, object + code, binary,\n or any other form resulting from mechanical transformation + or\n translation of the Source form.\n\n\nPermission for Use and Modification + Without Distribution\n\n(1) You are permitted to use the Standard Version and + create and use\nModified Versions for any purpose without restriction, provided + that\nyou do not Distribute the Modified Version.\n\n\nPermissions for Redistribution + of the Standard Version\n\n(2) You may Distribute verbatim copies of the Source + form of the\nStandard Version of this Package in any medium without restriction,\neither + gratis or for a Distributor Fee, provided that you duplicate\nall of the original + copyright notices and associated disclaimers. At\nyour discretion, such verbatim + copies may or may not include a\nCompiled form of the Package.\n\n(3) You may + apply any bug fixes, portability changes, and other\nmodifications made available + from the Copyright Holder. The resulting\nPackage will still be considered + the Standard Version, and as such\nwill be subject to the Original License.\n\n\nDistribution + of Modified Versions of the Package as Source \n\n(4) You may Distribute your + Modified Version as Source (either gratis\nor for a Distributor Fee, and with + or without a Compiled form of the\nModified Version) provided that you clearly + document how it differs\nfrom the Standard Version, including, but not limited + to, documenting\nany non-standard features, executables, or modules, and provided + that\nyou do at least ONE of the following:\n\n (a) make the Modified Version + available to the Copyright Holder\n of the Standard Version, under the Original + License, so that the\n Copyright Holder may include your modifications in + the Standard\n Version.\n\n (b) ensure that installation of your Modified + Version does not\n prevent the user installing or running the Standard Version. + In\n addition, the Modified Version must bear a name that is different\n + \ from the name of the Standard Version.\n\n (c) allow anyone who receives + a copy of the Modified Version to\n make the Source form of the Modified + Version available to others\n under\n\t\t\n\t(i) the Original License or\n\n\t(ii) + \ a license that permits the licensee to freely copy,\n\tmodify and redistribute + the Modified Version using the same\n\tlicensing terms that apply to the copy + that the licensee\n\treceived, and requires that the Source form of the Modified\n\tVersion, + and of any works derived from it, be made freely\n\tavailable in that license + fees are prohibited but Distributor\n\tFees are allowed.\n\n\nDistribution of + Compiled Forms of the Standard Version \nor Modified Versions without the Source\n\n(5) + \ You may Distribute Compiled forms of the Standard Version without\nthe Source, + provided that you include complete instructions on how to\nget the Source of + the Standard Version. Such instructions must be\nvalid at the time of your + distribution. If these instructions, at any\ntime while you are carrying out + such distribution, become invalid, you\nmust provide new instructions on demand + or cease further distribution.\nIf you provide valid instructions or cease distribution + within thirty\ndays after you become aware that the instructions are invalid, + then\nyou do not forfeit any of your rights under this license.\n\n(6) You + may Distribute a Modified Version in Compiled form without\nthe Source, provided + that you comply with Section 4 with respect to\nthe Source of the Modified Version.\n\n\nAggregating + or Linking the Package \n\n(7) You may aggregate the Package (either the Standard + Version or\nModified Version) with other packages and Distribute the resulting\naggregation + provided that you do not charge a licensing fee for the\nPackage. Distributor + Fees are permitted, and licensing fees for other\ncomponents in the aggregation + are permitted. The terms of this license\napply to the use and Distribution + of the Standard or Modified Versions\nas included in the aggregation.\n\n(8) + You are permitted to link Modified and Standard Versions with\nother works, + to embed the Package in a larger work of your own, or to\nbuild stand-alone + binary or bytecode versions of applications that\ninclude the Package, and Distribute + the result without restriction,\nprovided the result does not expose a direct + interface to the Package.\n\n\nItems That are Not Considered Part of a Modified + Version \n\n(9) Works (including, but not limited to, modules and scripts) that\nmerely + extend or make use of the Package, do not, by themselves, cause\nthe Package + to be a Modified Version. In addition, such works are not\nconsidered parts + of the Package itself, and are not subject to the\nterms of this license.\n\n\nGeneral + Provisions\n\n(10) Any use, modification, and distribution of the Standard + or\nModified Versions is governed by this Artistic License. By using,\nmodifying + or distributing the Package, you accept this license. Do not\nuse, modify, or + distribute the Package, if you do not accept this\nlicense.\n\n(11) If your + Modified Version has been derived from a Modified\nVersion made by someone other + than you, you are nevertheless required\nto ensure that your Modified Version + complies with the requirements of\nthis license.\n\n(12) This license does + not grant you the right to use any trademark,\nservice mark, tradename, or logo + of the Copyright Holder.\n\n(13) This license includes the non-exclusive, worldwide,\nfree-of-charge + patent license to make, have made, use, offer to sell,\nsell, import and otherwise + transfer the Package with respect to any\npatent claims licensable by the Copyright + Holder that are necessarily\ninfringed by the Package. If you institute patent + litigation\n(including a cross-claim or counterclaim) against any party alleging\nthat + the Package constitutes direct or contributory patent\ninfringement, then this + Artistic License to you shall terminate on the\ndate that such litigation is + filed.\n\n(14) Disclaimer of Warranty:\nTHE PACKAGE IS PROVIDED BY THE COPYRIGHT + HOLDER AND CONTRIBUTORS \"AS\nIS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. + THE IMPLIED\nWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, + OR\nNON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL\nLAW. + UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL\nBE LIABLE FOR + ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL\nDAMAGES ARISING IN ANY WAY + OUT OF THE USE OF THE PACKAGE, EVEN IF\nADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n" + url: http://www.perlfoundation.org/attachment/legal/artistic-2_0.txt + required_fields: [] + links: + self: https://api.staging.osf.io/v2/licenses/5c252c8e0989e100220edb74/ + - id: 5c252c8e0989e100220edb75 + type: licenses + attributes: + name: CC0 1.0 Universal + text: | + Statement of Purpose + + The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an "owner") of an original work of authorship and/or a database (each, a "Work"). + + Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works ("Commons") that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others. + + For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the "Affirmer"), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights. + + 1. Copyright and Related Rights. A Work made available under CC0 may be protected by copyright and related or neighboring rights ("Copyright and Related Rights"). Copyright and Related Rights include, but are not limited to, the following: + + the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work; + moral rights retained by the original author(s) and/or performer(s); + publicity and privacy rights pertaining to a person's image or likeness depicted in a Work; + rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below; + rights protecting the extraction, dissemination, use and reuse of data in a Work; + database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and + other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof. + 2. Waiver. To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer's Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer's heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer's express Statement of Purpose. + + 3. Public License Fallback. Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer's express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer's Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "License"). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer's express Statement of Purpose. + + 4. Limitations and Disclaimers. + + No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document. + Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law. + Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person's Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work. + Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work. + url: https://creativecommons.org/publicdomain/zero/1.0/legalcode + required_fields: [] + links: + self: https://api.staging.osf.io/v2/licenses/5c252c8e0989e100220edb75/ + - id: 5c252c8e0989e100220edb7b + type: licenses + attributes: + name: Eclipse Public License 1.0 + text: | + Eclipse Public License - v 1.0 + + THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + + 1. DEFINITIONS + + "Contribution" means: + + a) in the case of the initial Contributor, the initial code and documentation distributed under this Agreement, and + b) in the case of each subsequent Contributor: + i) changes to the Program, and + ii) additions to the Program; + where such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution 'originates' from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program. + "Contributor" means any person or entity that distributes the Program. + + "Licensed Patents" mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program. + + "Program" means the Contributions distributed in accordance with this Agreement. + + "Recipient" means anyone who receives the Program under this Agreement, including all Contributors. + + 2. GRANT OF RIGHTS + + a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form. + b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder. + c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program. + d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement. + 3. REQUIREMENTS + + A Contributor may choose to distribute the Program in object code form under its own license agreement, provided that: + + a) it complies with the terms and conditions of this Agreement; and + b) its license agreement: + i) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose; + ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; + iii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and + iv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange. + When the Program is made available in source code form: + + a) it must be made available under this Agreement; and + b) a copy of this Agreement must be included with each copy of the Program. + Contributors may not remove or alter any copyright notices contained within the Program. + + Each Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution. + + 4. COMMERCIAL DISTRIBUTION + + Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense. + + For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages. + + 5. NO WARRANTY + + EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement , including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations. + + 6. DISCLAIMER OF LIABILITY + + EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + 7. GENERAL + + If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable. + + If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed. + + All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive. + + Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved. + + This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation. + url: http://www.eclipse.org/legal/epl-v10.html + required_fields: [] + links: + self: https://api.staging.osf.io/v2/licenses/5c252c8e0989e100220edb7b/ + - id: 5c252c8e0989e100220edb7c + type: licenses + attributes: + name: Mozilla Public License 2.0 + text: | + Mozilla Public License + Version 2.0 + + 1. Definitions + + 1.1. “Contributor” + means each individual or legal entity that creates, contributes to the creation of, or owns Covered Software. + + 1.2. “Contributor Version” + means the combination of the Contributions of others (if any) used by a Contributor and that particular Contributor’s Contribution. + + 1.3. “Contribution” + means Covered Software of a particular Contributor. + + 1.4. “Covered Software” + means Source Code Form to which the initial Contributor has attached the notice in Exhibit A, the Executable Form of such Source Code Form, and Modifications of such Source Code Form, in each case including portions thereof. + + 1.5. “Incompatible With Secondary Licenses” + means + + that the initial Contributor has attached the notice described in Exhibit B to the Covered Software; or + + that the Covered Software was made available under the terms of version 1.1 or earlier of the License, but not also under the terms of a Secondary License. + + 1.6. “Executable Form” + means any form of the work other than Source Code Form. + + 1.7. “Larger Work” + means a work that combines Covered Software with other material, in a separate file or files, that is not Covered Software. + + 1.8. “License” + means this document. + + 1.9. “Licensable” + means having the right to grant, to the maximum extent possible, whether at the time of the initial grant or subsequently, any and all of the rights conveyed by this License. + + 1.10. “Modifications” + means any of the following: + + any file in Source Code Form that results from an addition to, deletion from, or modification of the contents of Covered Software; or + + any new file in Source Code Form that contains any Covered Software. + + 1.11. “Patent Claims” of a Contributor + means any patent claim(s), including without limitation, method, process, and apparatus claims, in any patent Licensable by such Contributor that would be infringed, but for the grant of the License, by the making, using, selling, offering for sale, having made, import, or transfer of either its Contributions or its Contributor Version. + + 1.12. “Secondary License” + means either the GNU General Public License, Version 2.0, the GNU Lesser General Public License, Version 2.1, the GNU Affero General Public License, Version 3.0, or any later versions of those licenses. + + 1.13. “Source Code Form” + means the form of the work preferred for making modifications. + + 1.14. “You” (or “Your”) + means an individual or a legal entity exercising rights under this License. For legal entities, “You” includes any entity that controls, is controlled by, or is under common control with You. For purposes of this definition, “control” means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity. + + 2. License Grants and Conditions + + 2.1. Grants + + Each Contributor hereby grants You a world-wide, royalty-free, non-exclusive license: + + under intellectual property rights (other than patent or trademark) Licensable by such Contributor to use, reproduce, make available, modify, display, perform, distribute, and otherwise exploit its Contributions, either on an unmodified basis, with Modifications, or as part of a Larger Work; and + + under Patent Claims of such Contributor to make, use, sell, offer for sale, have made, import, and otherwise transfer either its Contributions or its Contributor Version. + + 2.2. Effective Date + + The licenses granted in Section 2.1 with respect to any Contribution become effective for each Contribution on the date the Contributor first distributes such Contribution. + + 2.3. Limitations on Grant Scope + + The licenses granted in this Section 2 are the only rights granted under this License. No additional rights or licenses will be implied from the distribution or licensing of Covered Software under this License. Notwithstanding Section 2.1(b) above, no patent license is granted by a Contributor: + + for any code that a Contributor has removed from Covered Software; or + + for infringements caused by: (i) Your and any other third party’s modifications of Covered Software, or (ii) the combination of its Contributions with other software (except as part of its Contributor Version); or + + under Patent Claims infringed by Covered Software in the absence of its Contributions. + + This License does not grant any rights in the trademarks, service marks, or logos of any Contributor (except as may be necessary to comply with the notice requirements in Section 3.4). + + 2.4. Subsequent Licenses + + No Contributor makes additional grants as a result of Your choice to distribute the Covered Software under a subsequent version of this License (see Section 10.2) or under the terms of a Secondary License (if permitted under the terms of Section 3.3). + + 2.5. Representation + + Each Contributor represents that the Contributor believes its Contributions are its original creation(s) or it has sufficient rights to grant the rights to its Contributions conveyed by this License. + + 2.6. Fair Use + + This License is not intended to limit any rights You have under applicable copyright doctrines of fair use, fair dealing, or other equivalents. + + 2.7. Conditions + + Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted in Section 2.1. + + 3. Responsibilities + + 3.1. Distribution of Source Form + + All distribution of Covered Software in Source Code Form, including any Modifications that You create or to which You contribute, must be under the terms of this License. You must inform recipients that the Source Code Form of the Covered Software is governed by the terms of this License, and how they can obtain a copy of this License. You may not attempt to alter or restrict the recipients’ rights in the Source Code Form. + + 3.2. Distribution of Executable Form + + If You distribute Covered Software in Executable Form then: + + such Covered Software must also be made available in Source Code Form, as described in Section 3.1, and You must inform recipients of the Executable Form how they can obtain a copy of such Source Code Form by reasonable means in a timely manner, at a charge no more than the cost of distribution to the recipient; and + + You may distribute such Executable Form under the terms of this License, or sublicense it under different terms, provided that the license for the Executable Form does not attempt to limit or alter the recipients’ rights in the Source Code Form under this License. + + 3.3. Distribution of a Larger Work + + You may create and distribute a Larger Work under terms of Your choice, provided that You also comply with the requirements of this License for the Covered Software. If the Larger Work is a combination of Covered Software with a work governed by one or more Secondary Licenses, and the Covered Software is not Incompatible With Secondary Licenses, this License permits You to additionally distribute such Covered Software under the terms of such Secondary License(s), so that the recipient of the Larger Work may, at their option, further distribute the Covered Software under the terms of either this License or such Secondary License(s). + + 3.4. Notices + + You may not remove or alter the substance of any license notices (including copyright notices, patent notices, disclaimers of warranty, or limitations of liability) contained within the Source Code Form of the Covered Software, except that You may alter any license notices to the extent required to remedy known factual inaccuracies. + + 3.5. Application of Additional Terms + + You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Software. However, You may do so only on Your own behalf, and not on behalf of any Contributor. You must make it absolutely clear that any such warranty, support, indemnity, or liability obligation is offered by You alone, and You hereby agree to indemnify every Contributor for any liability incurred by such Contributor as a result of warranty, support, indemnity or liability terms You offer. You may include additional disclaimers of warranty and limitations of liability specific to any jurisdiction. + + 4. Inability to Comply Due to Statute or Regulation + + If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Software due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be placed in a text file included with all distributions of the Covered Software under this License. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it. + + 5. Termination + + 5.1. The rights granted under this License will terminate automatically if You fail to comply with any of its terms. However, if You become compliant, then the rights granted under this License from a particular Contributor are reinstated (a) provisionally, unless and until such Contributor explicitly and finally terminates Your grants, and (b) on an ongoing basis, if such Contributor fails to notify You of the non-compliance by some reasonable means prior to 60 days after You have come back into compliance. Moreover, Your grants from a particular Contributor are reinstated on an ongoing basis if such Contributor notifies You of the non-compliance by some reasonable means, this is the first time You have received notice of non-compliance with this License from such Contributor, and You become compliant prior to 30 days after Your receipt of the notice. + + 5.2. If You initiate litigation against any entity by asserting a patent infringement claim (excluding declaratory judgment actions, counter-claims, and cross-claims) alleging that a Contributor Version directly or indirectly infringes any patent, then the rights granted to You by any and all Contributors for the Covered Software under Section 2.1 of this License shall terminate. + + 5.3. In the event of termination under Sections 5.1 or 5.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or Your distributors under this License prior to termination shall survive termination. + + 6. Disclaimer of Warranty + + Covered Software is provided under this License on an “as is” basis, without warranty of any kind, either expressed, implied, or statutory, including, without limitation, warranties that the Covered Software is free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality and performance of the Covered Software is with You. Should any Covered Software prove defective in any respect, You (not any Contributor) assume the cost of any necessary servicing, repair, or correction. This disclaimer of warranty constitutes an essential part of this License. No use of any Covered Software is authorized under this License except under this disclaimer. + + 7. Limitation of Liability + + Under no circumstances and under no legal theory, whether tort (including negligence), contract, or otherwise, shall any Contributor, or anyone who distributes Covered Software as permitted above, be liable to You for any direct, indirect, special, incidental, or consequential damages of any character including, without limitation, damages for lost profits, loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses, even if such party shall have been informed of the possibility of such damages. This limitation of liability shall not apply to liability for death or personal injury resulting from such party’s negligence to the extent applicable law prohibits such limitation. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so this exclusion and limitation may not apply to You. + + 8. Litigation + + Any litigation relating to this License may be brought only in the courts of a jurisdiction where the defendant maintains its principal place of business and such litigation shall be governed by laws of that jurisdiction, without reference to its conflict-of-law provisions. Nothing in this Section shall prevent a party’s ability to bring cross-claims or counter-claims. + + 9. Miscellaneous + + This License represents the complete agreement concerning the subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not be used to construe this License against a Contributor. + + 10. Versions of the License + + 10.1. New Versions + + Mozilla Foundation is the license steward. Except as provided in Section 10.3, no one other than the license steward has the right to modify or publish new versions of this License. Each version will be given a distinguishing version number. + + 10.2. Effect of New Versions + + You may distribute the Covered Software under the terms of the version of the License under which You originally received the Covered Software, or under the terms of any subsequent version published by the license steward. + + 10.3. Modified Versions + + If you create software not governed by this License, and you want to create a new license for such software, you may create and use a modified version of this License if you rename the license and remove any references to the name of the license steward (except to note that such modified license differs from this License). + + 10.4. Distributing Source Code Form that is Incompatible With Secondary Licenses + + If You choose to distribute Source Code Form that is Incompatible With Secondary Licenses under the terms of this version of the License, the notice described in Exhibit B of this License must be attached. + + Exhibit A - Source Code Form License Notice + + This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. + + If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice. + + You may add additional accurate notices of copyright ownership. + + Exhibit B - “Incompatible With Secondary Licenses” Notice + + This Source Code Form is “Incompatible With Secondary Licenses”, as defined by the Mozilla Public License, v. 2.0. + url: https://www.mozilla.org/MPL/2.0/ + required_fields: [] + links: + self: https://api.staging.osf.io/v2/licenses/5c252c8e0989e100220edb7c/ + meta: + total: 5 + per_page: 10 + version: '2.20' + links: + self: https://api.staging.osf.io/v2/providers/registrations/temp/licenses/ + first: + last: + prev: + next: diff --git a/swagger-spec/registration_providers/list.yaml b/swagger-spec/registration_providers/list.yaml new file mode 100644 index 0000000..ffcf91c --- /dev/null +++ b/swagger-spec/registration_providers/list.yaml @@ -0,0 +1,82 @@ +# /registration_providers/ +get: + summary: List all Registration Providers + description: >- + + A paginated list of all Registration Providers. + The returned Registration Providers are sorted by their creation date, with the most recent + registrations appearing first. + + #### Returns + + Returns a JSON object containing `data` and `links` keys. + + + The `data` key contains an array of 10 Registration providers. + Each resource in the array is a separate Registration provider object. + + + The `links` key contains a dictionary of links that can be used + for [pagination](#tag/Pagination). + + + This request should never return an error. + + #### Filtering + + You can optionally request that the response only include preprint providers that + match your filters by utilizing the `filter` query parameter, e.g. + https://api.osf.io/v2/registration_providers/?filter[id]=osf. + + + Preprint Providers may be filtered by their `id`, `name`, and `description` + + tags: + - Registration Providers + operationId: registration_provider_list + x-response-schema: 'Registration Provider' + responses: + '200': + description: 'OK' + schema: + $ref: 'definition.yaml' + examples: + application/json: + data: + - relationships: + licenses_acceptable: + links: + related: + href: https://api.osf.io/v2/registration_providers/osf/licenses/ + meta: {} + taxonomies: + links: + related: + href: https://api.osf.io/v2/registration_providers/osf/taxonomies/ + meta: {} + registrations: + links: + related: + href: https://api.osf.io/v2/registration_providers/osf/registrations/ + meta: {} + links: + self: https://api.osf.io/v2/registration_providers/osf/ + registrations: https://api.osf.io/v2/registration_providers/osf/registrations/ + external_url: https://osf.io/registrations/ + attributes: + social_instagram: '' + advisory_board: '' + email_support: '' + banner_path: "/static/img/registration_providers/cos-logo.png" + logo_path: "/static/img/registration_providers/cos-logo.png" + subjects_acceptable: [] + description: A scholarly commons to connect the entire research cycle + social_facebook: '' + header_text: '' + social_twitter: '' + email_contact: '' + example: khbvy + name: Open Science Framework + domain: 'osf.io' + type: registration_providers + id: osf diff --git a/swagger-spec/registration_providers/provider_taxonomies_highlitghted_list.yaml b/swagger-spec/registration_providers/provider_taxonomies_highlighted_list.yaml similarity index 100% rename from swagger-spec/registration_providers/provider_taxonomies_highlitghted_list.yaml rename to swagger-spec/registration_providers/provider_taxonomies_highlighted_list.yaml diff --git a/swagger-spec/registration_providers/registrations_list.yaml b/swagger-spec/registration_providers/registrations_list.yaml index 16ff05b..d76bc0c 100644 --- a/swagger-spec/registration_providers/registrations_list.yaml +++ b/swagger-spec/registration_providers/registrations_list.yaml @@ -37,7 +37,7 @@ get: data: type: array items: - $ref: './definition.yaml' + $ref: '../registrations/definition.yaml' links: type: object properties: diff --git a/swagger-spec/registration_providers/registrations_schema_list.yaml b/swagger-spec/registration_providers/registrations_schema_list.yaml deleted file mode 100644 index 888da64..0000000 --- a/swagger-spec/registration_providers/registrations_schema_list.yaml +++ /dev/null @@ -1,132 +0,0 @@ -# /schemas/registrations/ -get: - summary: List Registration Schemas - description: >- - Retrieve a list of all available Registration Schemas. - - Registration Schemas define the structure and content of registration forms. Each schema outlines the fields that users must complete when registering an OSF project. Schemas may include required and optional questions, supporting different types of research workflows and data collections. - - Registration Schemas are maintained by the Center for Open Science and approved affiliated institutions. Some schemas are globally available, while others may be specific to certain providers. - - #### Permissions - - Public endpoint. No authentication required. - - All registration schemas are available to any user. - - #### Returns - - A JSON object with a `data` key containing an array of registration schemas. - - Each schema includes metadata such as name, description, and schema versioning information. - - tags: - - Registration Providers - - operationId: registrations_schema_list - - parameters: - - in: query - name: page - type: integer - required: false - description: Page number of results to return (pagination). - - - in: query - name: per_page - type: integer - required: false - description: Number of results per page (default 10, maximum 100). - - - in: query - name: filter[name] - type: string - required: false - description: Filter registration schemas by their name. - - - in: query - name: filter[active] - type: boolean - required: false - description: Filter registration schemas by their active status (`true` or `false`). - - responses: - '200': - description: Successful retrieval of registration schemas. - schema: - type: object - properties: - data: - type: array - items: - $ref: './definition.yaml' - links: - type: object - properties: - self: - type: string - next: - type: string - description: URL to the next page of results (if applicable). - prev: - type: string - description: URL to the previous page of results (if applicable). - meta: - type: object - properties: - total: - type: integer - description: Total number of registration schemas available. - per_page: - type: integer - description: Number of schemas returned per page. - version: - type: string - description: API version. - - examples: - application/json: - data: - - id: "prereg-challenge" - type: "registration_schemas" - attributes: - name: "Prereg Challenge" - description: "A schema supporting pre-registration of research plans for the Preregistration Challenge." - schema_version: 1 - active: true - schema: - - id: "q1" - type: "object" - title: "Research Questions" - properties: - text: "What is the main research question or hypothesis?" - date_created: "2017-06-01T00:00:00Z" - date_modified: "2023-10-01T00:00:00Z" - links: - self: "https://api.test.osf.io/v2/schemas/registrations/prereg-challenge/" - - id: "osf-registration" - type: "registration_schemas" - attributes: - name: "OSF-Standard Registration" - description: "The default OSF registration schema for general use." - schema_version: 2 - active: true - schema: - - id: "q1" - type: "object" - title: "Purpose of Registration" - properties: - text: "What is the purpose of this registration?" - date_created: "2015-01-01T00:00:00Z" - date_modified: "2024-01-01T00:00:00Z" - links: - self: "https://api.test.osf.io/v2/schemas/registrations/osf-registration/" - links: - self: "https://api.test.osf.io/v2/schemas/registrations/" - next: "https://api.test.osf.io/v2/schemas/registrations/?page=2" - prev: null - meta: - total: 25 - per_page: 10 - version: "2.0" - - '400': - description: Bad Request. Invalid input provided. - '404': - description: Not Found. No registration schemas match the given parameters. diff --git a/swagger-spec/registration_providers/registration_requests_list.yaml b/swagger-spec/registration_providers/requests_list.yaml similarity index 97% rename from swagger-spec/registration_providers/registration_requests_list.yaml rename to swagger-spec/registration_providers/requests_list.yaml index 2c17fc5..25d41c4 100644 --- a/swagger-spec/registration_providers/registration_requests_list.yaml +++ b/swagger-spec/registration_providers/requests_list.yaml @@ -1,5 +1,4 @@ -# /registrations/{provider_id}/requests/ - +# providers/registrations/{provider_id}/requests/ get: summary: List Registration Requests description: >- @@ -39,7 +38,7 @@ get: data: type: array items: - $ref: './definition.yaml' + $ref: '../registration_request/definition.yaml' links: type: object properties: diff --git a/swagger-spec/registration_providers/schemas_list.yaml b/swagger-spec/registration_providers/schemas_list.yaml new file mode 100644 index 0000000..b5af5b6 --- /dev/null +++ b/swagger-spec/registration_providers/schemas_list.yaml @@ -0,0 +1,115 @@ +get: + summary: List Registration Schemas for a Provider + description: > + Retrieve a list of registration schemas available for a specific registration provider. + + Registration schemas define the structure and fields that users must complete when registering a project with the provider. + + #### Permissions + - No authentication required for public providers. + - Private providers may require authentication. + + #### Returns + - A JSON object with a `data` array containing the registration schemas. + + tags: + - Registration Providers + + operationId: registration_provider_schema_list + + produces: + - application/vnd.api+json + - application/json + + parameters: + - name: provider_id + in: path + required: true + type: string + description: The unique identifier of the registration provider. + + - name: filter[active] + in: query + type: boolean + required: false + description: Filter schemas by their active status. + + - name: page + in: query + type: integer + required: false + description: Page number of results to return (pagination). + + - name: per_page + in: query + type: integer + required: false + description: Number of results per page. + + responses: + '200': + description: Successful retrieval of registration schemas for the provider. + schema: + type: object + properties: + data: + type: array + items: + $ref: '../registration_schemas/definition.yaml' + links: + type: object + properties: + self: + type: string + example: 'https://api.osf.io/v2/providers/registrations/{provider_id}/schemas/' + next: + type: string + example: 'https://api.osf.io/v2/providers/registrations/{provider_id}/schemas/?page=2' + prev: + type: string + example: null + meta: + type: object + properties: + total: + type: integer + example: 5 + per_page: + type: integer + example: 10 + version: + type: string + example: '2.0' + examples: + application/json: + data: + - id: "prereg-challenge" + type: "registration-schemas" + attributes: + name: "Prereg Challenge" + description: "Pre-registration schema for the Preregistration Challenge." + schema_version: 1 + active: true + schema: + - id: "q1" + type: "object" + title: "Research Questions" + properties: + text: "What is your main research question?" + date_created: "2017-06-01T00:00:00Z" + date_modified: "2023-10-01T00:00:00Z" + links: + self: "https://api.osf.io/v2/schemas/registrations/prereg-challenge/" + links: + self: "https://api.osf.io/v2/providers/registrations/{provider_id}/schemas/" + next: null + prev: null + meta: + total: 1 + per_page: 10 + version: "2.0" + + '400': + description: Bad request. Invalid parameters or input. + '404': + description: Not found. Registration provider does not exist. diff --git a/swagger-spec/registration_providers/registrations_subjects_list.yaml b/swagger-spec/registration_providers/subjects_list.yaml similarity index 100% rename from swagger-spec/registration_providers/registrations_subjects_list.yaml rename to swagger-spec/registration_providers/subjects_list.yaml diff --git a/swagger-spec/registration_providers/registrations_submissions_list.yaml b/swagger-spec/registration_providers/submissions_list.yaml similarity index 95% rename from swagger-spec/registration_providers/registrations_submissions_list.yaml rename to swagger-spec/registration_providers/submissions_list.yaml index 4a1d691..387812d 100644 --- a/swagger-spec/registration_providers/registrations_submissions_list.yaml +++ b/swagger-spec/registration_providers/submissions_list.yaml @@ -1,8 +1,8 @@ -# /registrations/{provider_id}/submissions/ get: summary: List Submissions for a Registration - description: >- - Retrieve a list of submissions associated with a specific registration. + description: > + Retrieve a list of submissions associated with a specific registration. + A submission represents an attempt to add a registration to a collection, typically requiring moderation or approval. #### Permissions @@ -19,6 +19,9 @@ get: operationId: registrations_submissions_list + produces: + - application/json + parameters: - in: path name: provider_id @@ -33,11 +36,11 @@ get: description: | Filter submissions by their state. Available values: - - `in_progress` - - `pending` - - `accepted` - - `rejected` - - `removed` + - in_progress + - pending + - accepted + - rejected + - removed - in: query name: page @@ -56,6 +59,8 @@ get: description: Successful retrieval of the list of submissions for the registration. schema: type: object + required: + - data properties: data: type: array @@ -84,7 +89,6 @@ get: version: type: string description: API version. - examples: application/json: data: @@ -135,4 +139,3 @@ get: description: Forbidden. You do not have permission to view these submissions. '404': description: Not Found. No registration matches the given ID. - diff --git a/swagger-spec/registration_request/definition.yaml b/swagger-spec/registration_request/definition.yaml new file mode 100644 index 0000000..287f6fe --- /dev/null +++ b/swagger-spec/registration_request/definition.yaml @@ -0,0 +1,94 @@ + type: object + required: + - id + - type + - attributes + - relationships + - links + properties: + id: + type: string + description: Unique identifier for the registration request. + example: req1 + + type: + type: string + description: The type of this resource; always `registration_request`. + example: registration_request + + attributes: + type: object + required: + - request_type + - state + - justification + - date_created + properties: + request_type: + type: string + description: > + Type of the registration request. Common types include `withdrawal`. + example: withdrawal + state: + type: string + description: > + Current status of the request in the moderation workflow. + Examples include `pending`, `accepted`, `rejected`. + enum: + - pending + - accepted + - rejected + example: pending + justification: + type: string + description: > + Justification provided by the requester for making the request. + example: "Authors requested withdrawal due to data issues." + date_created: + type: string + format: date-time + description: The date and time when the request was created. + example: "2024-06-01T09:30:00Z" + + relationships: + type: object + required: + - creator + - target + properties: + creator: + type: object + description: The user who created the request. + properties: + data: + type: object + properties: + type: + type: string + example: users + id: + type: string + example: user123 + target: + type: object + description: The registration this request applies to. + properties: + data: + type: object + properties: + type: + type: string + example: registrations + id: + type: string + example: reg1 + + links: + type: object + description: Links related to this registration request. + properties: + self: + type: string + format: uri + description: Link to the detail page for this request. + example: "https://api.test.osf.io/v2/registrations/reg1/requests/req1/" \ No newline at end of file diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index e8a1d63..faa6d6a 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -1021,6 +1021,7 @@ paths: /schemas/registrations/: $ref: 'registration_schemas/list.yaml' + /schemas/registrations/{registration_schema_id}: $ref: 'registration_schemas/detail.yaml' @@ -1265,6 +1266,53 @@ paths: /registrations/{registration_id}/wikis/: $ref: 'registrations/wikis_list.yaml' + ############################ + # REGISTRATION PROVIDERS # + ############################ + + /providers/registrations/: + $ref: 'registration_providers/list.yaml' + + /providers/registrations/{provider_id}/: + $ref: 'registration_providers/detail.yaml' + + /providers/registrations/{provider_id}/registrations/: + $ref: 'registration_providers/registrations_list.yaml' + + /providers/registrations/{provider_id}/taxonomies/: + $ref: 'registration_providers/provider_taxonomies_list.yaml' + + /providers/registrations/{provider_id}/taxonomies/highlighted/: + $ref: 'registration_providers/provider_taxonomies_highlighted_list.yaml' + + /providers/registrations/{provider_id}/licenses/: + $ref: 'registration_providers/licenses_list.yaml' + + /providers/registrations/{provider_id}/actions/: + $ref: 'registration_providers/actions_list.yaml' + + /providers/registrations/{provider_id}/requests/: + $ref: 'registration_providers/requests_list.yaml' + + /providers/registrations/{provider_id}/schemas/: + $ref: 'registration_providers/schemas_list.yaml' + + /providers/registrations/{provider_id}/subjects/: + $ref: 'registration_providers/subjects_list.yaml' + + /providers/registrations/{provider_id}/submissions/: + $ref: 'registration_providers/submissions_list.yaml' + + /providers/registrations/{provider_id}/subjects/highlighted/: + $ref: 'registration_providers/subjects_highlighted_list.yaml' + + /providers/registrations/{provider_id}/moderators/: + $ref: 'registration_providers/moderators_list.yaml' + + /providers/registrations/{provider_id}/moderators/{moderator_id}/: + $ref: 'registration_providers/moderators_detail.yaml' + + ########################## # DRAFT REGISTRATIONS # ########################## @@ -1387,6 +1435,37 @@ paths: /collections/{collection_id}/collected_metadata/{cgm_id}/relationships/subjects/: $ref: 'collections/collected_metadata_subjects_relationships.yaml' + ############################ + # COLLECTION PROVIDERS # + ############################ + + /providers/collections/: + $ref: 'collection_providers/list.yaml' + + /providers/collections/{provider_id}/: + $ref: 'collection_providers/detail.yaml' + + /providers/collections/{provider_id}/licenses/: + $ref: 'collection_providers/licenses_list.yaml' + + /providers/collections/{provider_id}/taxonomies/: + $ref: 'collection_providers/provider_taxonomies_list.yaml' + + /providers/collections/{provider_id}/taxonomies/highlighted/: + $ref: 'collection_providers/provider_taxonomies_highlighted_list.yaml' + + /providers/collections/{provider_id}/submissions/: + $ref: 'collection_providers/submissions_list.yaml' + + /providers/collections/{provider_id}/subjects/highlighted/: + $ref: 'collection_providers/subjects_highlighted_list.yaml' + + /providers/collections/{provider_id}/moderators/: + $ref: 'collection_providers/moderators_list.yaml' + + /providers/collections/{provider_id}/moderators/{moderator_id}/: + $ref: 'collection_providers/moderators_detail.yaml' + ############################### # COLLECTIONS SUBMISSIONS # ############################### @@ -1415,10 +1494,10 @@ paths: $ref: 'collection_providers/detail.yaml' /provider/collections/{provider_id}/licenses/: - $ref: 'collection_providers/licenses.yaml' + $ref: 'collection_providers/licenses_list.yaml' /provider/collections/{provider_id}/submissions/: - $ref: 'collection_providers/submissions.yaml' + $ref: 'collection_providers/submissions_list.yaml' /provider/collections/{provider_id}/subjects/: $ref: 'collection_providers/subjects.yaml' From 784636710f63f9b505c3473c5b6caab110cd37e1 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Thu, 27 Mar 2025 10:41:05 -0400 Subject: [PATCH 17/21] improve draft registration institution and subjects relationships --- .../relationships_institutions_list.yaml | 64 ++++++++++++++----- .../relationships_subjects_list.yaml | 55 ++++++++++++---- 2 files changed, 93 insertions(+), 26 deletions(-) diff --git a/swagger-spec/draft_registrations/relationships_institutions_list.yaml b/swagger-spec/draft_registrations/relationships_institutions_list.yaml index a963680..cfc1898 100644 --- a/swagger-spec/draft_registrations/relationships_institutions_list.yaml +++ b/swagger-spec/draft_registrations/relationships_institutions_list.yaml @@ -1,6 +1,9 @@ get: summary: Retrieve affiliated institutions for a draft registration - description: Get all institutions affiliated with the draft registration. + description: > + Retrieve the list of institutions currently affiliated with a draft registration. + + Returns institution IDs in JSON:API relationship format. tags: - Draft Registrations - Institutions @@ -10,7 +13,7 @@ get: in: path required: true type: string - description: Draft registration ID. + description: The unique identifier of the draft registration. responses: '200': description: Institutions retrieved successfully. @@ -21,13 +24,18 @@ get: type: array items: type: object - required: [type, id] + required: + - type + - id properties: type: type: string example: institutions + description: The resource type; must be `institutions`. id: type: string + example: inst123 + description: The unique identifier of the institution. example: data: - type: institutions @@ -35,13 +43,16 @@ get: - type: institutions id: inst456 '403': - description: Forbidden. + description: Forbidden. You do not have permission to view affiliated institutions. '404': description: Draft registration not found. post: summary: Add affiliated institutions to a draft registration - description: Add institutions to the draft registration. + description: > + Add one or more institutions to a draft registration by their identifiers. + + The user must be affiliated with the institutions they are attempting to add. tags: - Draft Registrations - Institutions @@ -51,35 +62,48 @@ post: in: path required: true type: string - - in: body - name: body + description: The unique identifier of the draft registration. + - name: body + in: body + required: true + description: JSON:API list of institution identifiers to associate with the draft registration. schema: type: object + required: + - data properties: data: type: array items: type: object - required: [type, id] + required: + - type + - id properties: type: type: string example: institutions + description: The resource type; must be `institutions`. id: type: string + example: inst123 + description: The unique ID of the institution to add. responses: '204': description: Institutions added successfully. '400': - description: User is not affiliated with the institution. + description: Bad Request. User is not affiliated with the specified institution(s). '403': - description: Forbidden. + description: Forbidden. You do not have permission to add institutions. '404': description: Draft registration not found. delete: summary: Remove affiliated institutions from a draft registration - description: Remove institutions from the draft registration. + description: > + Remove one or more institutions from the draft registration by their identifiers. + + This operation only modifies the relationship and does not delete the institutions themselves. tags: - Draft Registrations - Institutions @@ -89,26 +113,36 @@ delete: in: path required: true type: string - - in: body - name: body + description: The unique identifier of the draft registration. + - name: body + in: body + required: true + description: JSON:API list of institution identifiers to disassociate from the draft registration. schema: type: object + required: + - data properties: data: type: array items: type: object - required: [type, id] + required: + - type + - id properties: type: type: string example: institutions + description: The resource type; must be `institutions`. id: type: string + example: inst456 + description: The unique ID of the institution to remove. responses: '204': description: Institutions removed successfully. '403': - description: Forbidden. + description: Forbidden. You do not have permission to modify institutions. '404': description: Draft registration not found. diff --git a/swagger-spec/draft_registrations/relationships_subjects_list.yaml b/swagger-spec/draft_registrations/relationships_subjects_list.yaml index 8865a8c..00930d3 100644 --- a/swagger-spec/draft_registrations/relationships_subjects_list.yaml +++ b/swagger-spec/draft_registrations/relationships_subjects_list.yaml @@ -1,7 +1,9 @@ - get: summary: Retrieve subjects relationship for a draft registration - description: Get the subjects associated with a draft registration. + description: > + Retrieve the list of subjects currently associated with a draft registration. + + This endpoint returns subject IDs in the JSON:API relationship format. tags: - Draft Registrations - Subjects @@ -22,13 +24,18 @@ get: type: array items: type: object + required: + - type + - id properties: type: type: string example: subjects + description: The resource type; always `subjects`. id: type: string - description: Subject ID + example: abc123 + description: The unique identifier for the subject. example: data: - type: subjects @@ -42,7 +49,10 @@ get: post: summary: Add subjects to a draft registration - description: Add subjects by ID to the draft registration. + description: > + Add one or more subjects to the draft registration by their identifiers. + + This modifies the subjects relationship and does not affect the subject resource itself. tags: - Draft Registrations - Subjects @@ -52,22 +62,32 @@ post: in: path required: true type: string - - in: body - name: body + description: The unique identifier of the draft registration. + - name: body + in: body + required: true + description: JSON:API list of subject identifiers to associate with the draft registration. schema: type: object + required: + - data properties: data: type: array items: type: object - required: [type, id] + required: + - type + - id properties: type: type: string example: subjects + description: The resource type; must be `subjects`. id: type: string + example: abc123 + description: The unique ID of the subject to add. responses: '204': description: Subjects added successfully. @@ -78,7 +98,10 @@ post: delete: summary: Remove subjects from a draft registration - description: Remove subjects from the draft registration by ID. + description: > + Remove one or more subjects from the draft registration by their identifiers. + + This only updates the relationship and does not delete the subject resource. tags: - Draft Registrations - Subjects @@ -88,22 +111,32 @@ delete: in: path required: true type: string - - in: body - name: body + description: The unique identifier of the draft registration. + - name: body + in: body + required: true + description: JSON:API list of subject identifiers to disassociate from the draft registration. schema: type: object + required: + - data properties: data: type: array items: type: object - required: [type, id] + required: + - type + - id properties: type: type: string example: subjects + description: The resource type; must be `subjects`. id: type: string + example: def456 + description: The unique ID of the subject to remove. responses: '204': description: Subjects removed successfully. From eb56556ccc4d598628a65df9986872b4fd13d72d Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Thu, 27 Mar 2025 12:17:13 -0400 Subject: [PATCH 18/21] fix issues with resources, subjects, custom metadata and guids --- swagger-spec/custom_metadata/files_list.yaml | 10 +- swagger-spec/custom_metadata/nodes_list.yaml | 56 ++-- swagger-spec/guids/detail.yaml | 60 ++-- swagger-spec/resources/definition.yaml | 140 +++++---- swagger-spec/resources/detail.yaml | 58 ++-- swagger-spec/resources/list.yaml | 285 +++++++++++-------- swagger-spec/subjects/children_list.yaml | 32 ++- swagger-spec/subjects/detail.yaml | 168 ++++++----- swagger-spec/subjects/list.yaml | 14 +- swagger-spec/swagger.yaml | 6 +- 10 files changed, 456 insertions(+), 373 deletions(-) diff --git a/swagger-spec/custom_metadata/files_list.yaml b/swagger-spec/custom_metadata/files_list.yaml index ade725d..95db474 100644 --- a/swagger-spec/custom_metadata/files_list.yaml +++ b/swagger-spec/custom_metadata/files_list.yaml @@ -7,16 +7,16 @@ get: tags: - Custom Metadata parameters: - - name: guid_id + - name: file_id in: path - description: The unique identifier (GUID) of the file. + description: The unique identifier of the file. required: true type: string responses: '200': description: Successfully retrieved custom file metadata record. schema: - $ref: './schemas/custom_file_metadata_record.yaml' + $ref: './definition_file.yaml' '401': description: Authentication credentials were not provided or are invalid. '403': @@ -35,9 +35,9 @@ patch: tags: - Custom Metadata parameters: - - name: guid_id + - name: file_id in: path - description: The unique identifier (GUID) of the file. + description: The unique identifier of the file. required: true type: string - name: body diff --git a/swagger-spec/custom_metadata/nodes_list.yaml b/swagger-spec/custom_metadata/nodes_list.yaml index 8745380..16450a5 100644 --- a/swagger-spec/custom_metadata/nodes_list.yaml +++ b/swagger-spec/custom_metadata/nodes_list.yaml @@ -1,30 +1,28 @@ - get: - summary: Retrieve custom item metadata for a node or preprint - description: > - Retrieve a custom item metadata record associated with a node or preprint by its GUID. - Custom item metadata includes fields like language, resource type, and funding information. - operationId: getCustomItemMetadataRecord - tags: - - Custom Metadata - parameters: - - name: guid_id - in: path - description: The unique identifier (GUID) of the node or preprint. - required: true - type: string - responses: - '200': - description: Successfully retrieved custom item metadata record. - schema: - $ref: 'definition_nodes.yaml' - '401': - description: Authentication credentials were not provided or are invalid. - '403': - description: You do not have permission to access this metadata record. - '404': - description: Metadata record not found. - security: - - osf_cookie: [] +get: + summary: Retrieve custom item metadata for a node or preprint + description: > + Retrieve a custom item metadata record associated with a node or preprint by its GUID. + Custom item metadata includes fields like language, resource type, and funding information. + operationId: getCustomItemMetadataRecord + tags: + - Custom Metadata + parameters: + - name: guid_id + in: path + description: The unique identifier (GUID) of the node or preprint. + required: true + type: string + responses: + '200': + description: Successfully retrieved custom item metadata record. + schema: + $ref: 'definition_nodes.yaml' + '401': + description: Authentication credentials were not provided or are invalid. + '403': + description: You do not have permission to access this metadata record. + '404': + description: Metadata record not found. patch: summary: Update custom item metadata for a node or preprint description: > @@ -57,6 +55,4 @@ patch: '403': description: You do not have permission to modify this metadata record. '404': - description: Metadata record not found. - security: - - osf_cookie: [] \ No newline at end of file + description: Metadata record not found. \ No newline at end of file diff --git a/swagger-spec/guids/detail.yaml b/swagger-spec/guids/detail.yaml index 8131727..ba6a669 100644 --- a/swagger-spec/guids/detail.yaml +++ b/swagger-spec/guids/detail.yaml @@ -3,47 +3,42 @@ get: description: | Retrieve a GUID object or be redirected to the most appropriate resource. - By default, this endpoint will redirect (`302 Found`) to the resource URL associated with the GUID. - If `?resolve=false` is passed as a query parameter, the request returns the GUID resource itself instead of redirecting. + By default, this endpoint redirects (`302 Found`) to the resource URL associated with the GUID. + If `?resolve=false` is passed, it returns the GUID resource object instead of redirecting. - This endpoint is helpful for resolving GUIDs that may refer to various OSF objects, including: - - Nodes - - Registrations - - Files - - Collections - - Preprints - - Users + GUIDs may reference nodes, registrations, files, collections, preprints, or users. ### Redirect Behavior - - If the GUID is valid and points to a resource with an API endpoint, you will be redirected to that resource. - - If the GUID is valid but refers to an object with no endpoint (e.g., a wiki page), you will get a `501 Not Implemented`. - - If the GUID does not exist or has been deleted, a `404 Not Found` or `410 Gone` response is returned. + - If the GUID refers to a supported resource, this will redirect to its detail endpoint. + - If it refers to an unsupported type (e.g., wiki), `501 Not Implemented` is returned. + - If the GUID is invalid or deleted, a `404` or `410` is returned. ### JSON Response Behavior - If `resolve=false` is provided as a query parameter, a `200 OK` response returns the GUID resource and relationships to its referent and custom metadata records. + - If `resolve=false` is used, a `200 OK` is returned with the GUID resource object. ### Permissions - - Public GUIDs are available to unauthenticated users. - - Private GUIDs require appropriate read permissions. + - Public GUIDs are accessible without authentication. + - Private GUIDs require appropriate access permissions. operationId: retrieveGuid tags: - GUIDs + produces: + - application/vnd.api+json parameters: - name: guid_id in: path - required: true type: string - description: | - The unique identifier for the GUID. - This can refer to nodes, registrations, files, collections, preprints, or users. + required: true + description: The unique identifier for the GUID. - name: resolve in: query - required: false type: boolean + required: false description: | - If true (default), redirects to the referent resource. - If false, returns a representation of the GUID resource itself. + If true (default), redirect to the referent resource. + If false, return a representation of the GUID resource. + responses: '200': description: Successfully retrieved the GUID resource. @@ -61,18 +56,22 @@ get: properties: id: type: string + description: The GUID string. example: abc123 type: type: string + description: The type of this resource. example: guids attributes: type: object - properties: {} + description: Optional metadata (usually empty). + example: {} relationships: type: object properties: referent: type: object + description: The resource this GUID points to. properties: links: type: object @@ -85,9 +84,11 @@ get: properties: type: type: string + description: Resource type of the referent. example: nodes custom_metadata: type: object + description: Link to any associated custom metadata record. properties: links: type: object @@ -101,18 +102,19 @@ get: self: type: string example: https://api.osf.io/v2/guids/abc123/ + description: API link to this GUID resource. html: type: string example: https://osf.io/abc123/ + description: Public web URL of this resource. + '302': - description: Redirect to the referent resource. + description: Redirects to the referent resource if `resolve=true` or omitted. '401': - description: Authentication credentials were not provided or are invalid. + description: Authentication required. '403': description: You do not have permission to view this GUID. '404': - description: The GUID does not exist. + description: GUID not found. '410': - description: The GUID once existed but has since been deleted. - produces: - - application/vnd.api+json + description: The GUID has been deleted. diff --git a/swagger-spec/resources/definition.yaml b/swagger-spec/resources/definition.yaml index a70f908..888beb2 100644 --- a/swagger-spec/resources/definition.yaml +++ b/swagger-spec/resources/definition.yaml @@ -1,83 +1,79 @@ - description: A resource associated with a registration, such as datasets, materials, code, or papers. +description: A resource associated with a registration, such as datasets, materials, code, or papers. +type: object +required: + - data +properties: + data: type: object required: - - data + - id + - type + - attributes properties: - data: + id: + type: string + description: Unique identifier of the resource. + example: "abc123" + type: + type: string + description: The type of the resource object. + example: "resources" + attributes: type: object - required: - - id - - type - - attributes properties: - id: + date_created: type: string - example: "abc123" - description: Unique identifier of the resource. - type: + format: date-time + example: "2024-01-01T00:00:00Z" + description: The date the resource was created. + date_modified: type: string - example: "resources" - description: The type of the resource object. - attributes: - type: object - properties: - date_created: - type: string - format: date-time - example: "2024-01-01T00:00:00Z" - description: The date the resource was created. - date_modified: - type: string - format: date-time - example: "2024-01-02T00:00:00Z" - description: The date the resource was last modified. - description: - type: string - example: "Dataset resource for analysis of trial results" - description: A brief description of the resource. - resource_type: - type: string - description: | - The type of the resource. Acceptable values include: - - data - - analytic_code - - materials - - papers - - supplements - example: "data" - finalized: - type: boolean - description: Indicates whether the resource has been finalized. - example: true - pid: - type: string - description: Persistent Identifier (PID) assigned to the resource. - example: "10.1234/osf.io/abcde" - relationships: + format: date-time + example: "2024-01-02T00:00:00Z" + description: The date the resource was last modified. + description: + type: string + description: A brief description of the resource. + example: "Dataset resource for analysis of trial results" + resource_type: + type: string + description: | + The type of the resource. Acceptable values include: + - data + - analytic_code + - materials + - papers + - supplements + example: "data" + finalized: + type: boolean + description: Indicates whether the resource has been finalized. + example: true + pid: + type: string + description: Persistent Identifier (PID) assigned to the resource. + example: "10.1234/osf.io/abcde" + relationships: + type: object + properties: + registration: type: object - description: Relationships for the resource. properties: - registration: + data: type: object properties: - data: - type: object - required: - - id - - type - properties: - id: - type: string - example: "reg123" - description: The unique identifier of the registration the resource is linked to. - type: - type: string - example: "registrations" - description: Type for the registration relationship. - links: - type: object - properties: - self: - type: string - description: The canonical API endpoint for this resource. - example: "https://api.osf.io/v2/resources/abc123/" \ No newline at end of file + id: + type: string + example: "reg123" + description: The unique identifier of the registration. + type: + type: string + example: "registrations" + description: Type for the registration. + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/resources/abc123/" + description: The canonical API endpoint for this resource. diff --git a/swagger-spec/resources/detail.yaml b/swagger-spec/resources/detail.yaml index 31110c1..b916165 100644 --- a/swagger-spec/resources/detail.yaml +++ b/swagger-spec/resources/detail.yaml @@ -1,7 +1,9 @@ get: summary: Retrieve a resource description: | - Retrieve details for a specific resource. + Retrieve the full metadata for a specific resource associated with a registration. + + A resource may include datasets, materials, code, papers, or supplements. tags: - Resources operationId: getResource @@ -13,20 +15,22 @@ get: description: The unique identifier of the resource. responses: '200': - description: Successful retrieval of resource + description: Successful retrieval of the resource. schema: $ref: 'definition.yaml' - '404': - description: Resource not found. '401': description: Authentication required. '403': description: Permission denied. + '404': + description: Resource not found. patch: summary: Update a resource description: | - Update details for a specific resource. + Update one or more metadata fields of a specific resource. + + Only the fields provided in the request payload will be updated. tags: - Resources operationId: updateResource @@ -35,11 +39,11 @@ patch: in: path required: true type: string - description: The unique identifier of the resource. - - name: body - in: body - description: Resource object to update + description: The unique identifier of the resource to update. + - in: body + name: body required: true + description: A JSON:API compliant object describing the updates. schema: type: object required: @@ -55,42 +59,56 @@ patch: id: type: string example: "abc123" + description: The ID of the resource being updated. type: type: string example: "resources" + description: The resource type — must be `"resources"`. attributes: type: object properties: description: type: string - example: "Updated resource description" + example: "Updated dataset description." + description: A short description of the resource. resource_type: type: string example: "materials" + description: | + Type of the resource. Allowed values: + - data + - analytic_code + - materials + - papers + - supplements finalized: type: boolean example: true + description: Whether the resource is finalized (locked for editing). pid: type: string example: "10.5678/resource.9012" + description: A persistent identifier (e.g. DOI) for the resource. responses: '200': - description: Successfully updated the resource + description: Resource updated successfully. schema: $ref: 'definition.yaml' '400': - description: Validation error or invalid data. - '404': - description: Resource not found. + description: Validation error or malformed request data. '401': description: Authentication required. '403': description: Permission denied. + '404': + description: Resource not found. delete: summary: Delete a resource description: | - Delete a specific resource. + Permanently delete a specific resource. + + Finalized resources or those linked to active registrations may not be deletable. tags: - Resources operationId: deleteResource @@ -99,13 +117,13 @@ delete: in: path required: true type: string - description: The unique identifier of the resource. + description: The unique identifier of the resource to delete. responses: '204': - description: Successfully deleted the resource - '404': - description: Resource not found. + description: Resource deleted successfully. No content returned. '401': description: Authentication required. '403': - description: Permission denied. \ No newline at end of file + description: Permission denied or resource cannot be deleted. + '404': + description: Resource not found. diff --git a/swagger-spec/resources/list.yaml b/swagger-spec/resources/list.yaml index d446d56..88b4ba3 100644 --- a/swagger-spec/resources/list.yaml +++ b/swagger-spec/resources/list.yaml @@ -1,155 +1,190 @@ - get: - summary: List resources - description: | - Retrieve a list of resources associated with registrations. - tags: - - Resources - operationId: listResources - responses: - '200': - description: Successful retrieval of resource list - schema: - type: object - properties: - data: - type: array - items: - type: object - required: - - id - - type - - attributes - - relationships - properties: - id: - type: string - example: "abc123" - type: - type: string - example: "resources" - attributes: - type: object - properties: - date_created: - type: string - format: date-time - example: "2024-01-01T00:00:00Z" - date_modified: - type: string - format: date-time - example: "2024-01-02T00:00:00Z" - description: - type: string - example: "Dataset resource" - resource_type: - type: string - example: "data" - finalized: - type: boolean - example: true - pid: - type: string - example: "10.1234/resource.5678" - relationships: - type: object - properties: - registration: - type: object - properties: - data: - type: object - properties: - id: - type: string - example: "reg123" - type: - type: string - example: "registrations" - links: - type: object - properties: - self: - type: string - example: "https://api.osf.io/v2/resources/abc123/" - meta: - type: object - properties: - total: - type: integer - example: 1 - per_page: - type: integer - example: 10 - page: - type: integer - example: 1 - '401': - description: Authentication required. - '403': - description: Permission denied. - - post: - summary: Create a new resource - description: | - Create a new resource associated with a registration. - tags: - - Resources - operationId: createResource - parameters: - - name: body - in: body - description: Resource object to create - required: true - schema: - type: object - required: - - data - properties: - data: +get: + summary: List resources + description: Retrieve a list of resources associated with registrations. + tags: + - Resources + operationId: listResources + responses: + '200': + description: Successful retrieval of resource list + schema: + type: object + properties: + data: + type: array + description: Array of resource objects. + items: type: object required: + - id - type - attributes - relationships properties: + id: + type: string + example: "abc123" + description: Unique identifier for the resource. type: type: string example: "resources" + description: "The type of this object: `resources`." attributes: type: object + description: Resource metadata. properties: + date_created: + type: string + format: date-time + example: "2024-01-01T00:00:00Z" + description: When the resource was created. + date_modified: + type: string + format: date-time + example: "2024-01-02T00:00:00Z" + description: When the resource was last updated. description: type: string example: "Dataset resource" + description: A short summary of the resource. resource_type: type: string example: "data" + description: > + The category of the resource. Valid values include: + - data + - analytic_code + - materials + - papers + - supplements + finalized: + type: boolean + example: true + description: Whether the resource is finalized and no longer editable. + pid: + type: string + example: "10.1234/resource.5678" + description: A persistent identifier (DOI) assigned to this resource. relationships: type: object + description: Relationships for the resource. properties: registration: type: object + description: The registration associated with the resource. properties: data: type: object - required: - - type - - id properties: - type: - type: string - example: "registrations" id: type: string example: "reg123" - responses: - '201': - description: Successfully created a new resource - schema: - $ref: 'definition.yaml' - '400': - description: Validation error or invalid data. - '401': - description: Authentication required. - '403': - description: Permission denied. \ No newline at end of file + description: ID of the related registration. + type: + type: string + example: "registrations" + description: Type of the related object. + links: + type: object + description: Related API URLs for this resource. + properties: + self: + type: string + example: "https://api.osf.io/v2/resources/abc123/" + description: URL to the resource detail. + meta: + type: object + description: Metadata for pagination. + properties: + total: + type: integer + example: 1 + description: Total number of resources. + per_page: + type: integer + example: 10 + description: Results per page. + page: + type: integer + example: 1 + description: Current page number. + '401': + description: Authentication required. + '403': + description: Permission denied. + +post: + summary: Create a new resource + description: Create a new resource associated with a registration. + tags: + - Resources + operationId: createResource + parameters: + - name: body + in: body + description: JSON:API-compliant resource creation payload. + required: true + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - attributes + - relationships + properties: + type: + type: string + example: "resources" + description: Must be `resources`. + attributes: + type: object + description: Metadata about the new resource. + required: + - description + - resource_type + properties: + description: + type: string + example: "Dataset resource" + description: Short text describing the resource. + resource_type: + type: string + example: "data" + description: Type of resource (e.g., data, materials). + relationships: + type: object + description: Relationships for the resource. + properties: + registration: + type: object + description: The registration this resource is linked to. + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + example: "registrations" + description: Must be `registrations`. + id: + type: string + example: "reg123" + description: ID of the related registration. + responses: + '201': + description: Successfully created a new resource. + schema: + $ref: 'definition.yaml' + '400': + description: Validation error or invalid data. + '401': + description: Authentication required. + '403': + description: Permission denied. diff --git a/swagger-spec/subjects/children_list.yaml b/swagger-spec/subjects/children_list.yaml index ba43b4e..aef5484 100644 --- a/swagger-spec/subjects/children_list.yaml +++ b/swagger-spec/subjects/children_list.yaml @@ -1,17 +1,24 @@ get: summary: List child subjects for a given subject description: | - Retrieve all immediate child subjects for the given taxonomy subject. - Subjects are categorized hierarchically. + Retrieve all immediate child taxonomy subjects of the specified parent subject. + + Taxonomy subjects are structured hierarchically. This endpoint returns only the direct descendants (children) of the given subject. + + ### Permissions + - Publicly accessible (no authentication required). + operationId: listSubjectChildren tags: - Subjects + produces: + - application/vnd.api+json parameters: - name: subject_id in: path - description: The unique identifier of the parent subject. - required: true type: string + required: true + description: The unique identifier of the parent taxonomy subject. responses: '200': description: Successful retrieval of child subjects. @@ -26,27 +33,33 @@ get: - id - type - attributes + - relationships properties: id: type: string example: "child123" + description: Unique identifier for the subject. type: type: string example: "subjects" + description: The resource type. attributes: type: object properties: text: type: string example: "Sub-discipline Example" + description: Human-readable name of the subject. taxonomy_name: type: string example: "OSF" + description: Name of the taxonomy this subject belongs to. relationships: type: object properties: parent: type: object + description: The parent of this subject. properties: data: type: object @@ -57,11 +70,14 @@ get: id: type: string example: "abc123" + description: ID of the parent subject. type: type: string example: "subjects" + description: The resource type (subjects). children: type: object + description: Nested relationship to this subject’s own children. properties: links: type: object @@ -69,8 +85,10 @@ get: related: type: string example: "https://api.osf.io/v2/subjects/child123/children/" + description: Link to this subject's own children. links: type: object + description: Pagination links. properties: self: type: string @@ -83,19 +101,21 @@ get: example: "https://api.osf.io/v2/subjects/{subject_id}/children/?page=1" meta: type: object + description: Pagination metadata. properties: total: type: integer example: 20 + description: Total number of child subjects available. per_page: type: integer example: 10 + description: Number of results returned per page. page: type: integer example: 1 + description: Current page number. '404': description: Parent subject not found. security: - osf_cookie: [] - produces: - - application/vnd.api+json diff --git a/swagger-spec/subjects/detail.yaml b/swagger-spec/subjects/detail.yaml index 4233ff5..0aed397 100644 --- a/swagger-spec/subjects/detail.yaml +++ b/swagger-spec/subjects/detail.yaml @@ -1,87 +1,97 @@ - get: - summary: Retrieve a single taxonomy subject - description: | - Retrieve detailed information about a specific taxonomy subject by its ID. +get: + summary: Retrieve a single taxonomy subject + description: | + Retrieve detailed information about a specific taxonomy subject by its ID. - ### Permissions - - Publicly accessible (no authentication required). - - operationId: retrieveSubject - tags: - - Subjects - parameters: - - name: subject_id - in: path - description: The unique identifier of the subject. - required: true - type: string - responses: - '200': - description: Successfully retrieved the subject. - schema: - type: object - properties: - data: - type: object - required: - - id - - type - - attributes - - relationships - properties: - id: - type: string - example: "abc123" - type: - type: string - example: "subjects" - attributes: - type: object - properties: - text: - type: string - example: "Climate Change" - taxonomy_name: - type: string - example: "OSF" - relationships: - type: object - properties: - parent: - type: object - properties: - data: + ### Permissions + - Publicly accessible (no authentication required). + operationId: retrieveSubject + tags: + - Subjects + produces: + - application/vnd.api+json + parameters: + - name: subject_id + in: path + description: The unique identifier of the subject. + required: true + type: string + responses: + '200': + description: Successfully retrieved the subject. + schema: + type: object + properties: + data: + type: object + required: + - id + - type + - attributes + - relationships + properties: + id: + type: string + example: "abc123" + description: The unique ID of the subject. + type: + type: string + example: "subjects" + description: The resource type. + attributes: + type: object + properties: + text: + type: string + example: "Climate Change" + description: Human-readable label for the subject. + taxonomy_name: + type: string + example: "OSF" + description: The taxonomy classification this subject belongs to. + relationships: + type: object + properties: + parent: + type: object + description: The parent subject of this subject (if any). + properties: + data: + type: object + properties: + id: + type: string + example: "parent123" + description: ID of the parent subject. + type: + type: string + example: "subjects" + description: Resource type (subjects). + children: + type: object + description: The direct children subjects of this subject. + properties: + data: + type: array + items: type: object properties: id: type: string - example: "parent123" + example: "child123" + description: ID of the child subject. type: type: string example: "subjects" - children: - type: object - properties: - data: - type: array - items: - type: object - properties: - id: - type: string - example: "child123" - type: - type: string - example: "subjects" - links: - type: object - properties: - self: - type: string - example: "https://api.osf.io/v2/subjects/abc123/" - '404': - description: Subject not found. - security: - - osf_cookie: [] - produces: - - application/vnd.api+json + description: Resource type (subjects). + links: + type: object + properties: + self: + type: string + example: "https://api.osf.io/v2/subjects/abc123/" + description: Canonical link to this subject resource. + '404': + description: Subject not found. + security: + - osf_cookie: [] diff --git a/swagger-spec/subjects/list.yaml b/swagger-spec/subjects/list.yaml index 1923fae..9659fce 100644 --- a/swagger-spec/subjects/list.yaml +++ b/swagger-spec/subjects/list.yaml @@ -6,10 +6,11 @@ get: ### Permissions - Publicly accessible (no authentication required). - operationId: listSubjects tags: - Subjects + produces: + - application/vnd.api+json parameters: - name: filter[text] in: query @@ -59,9 +60,11 @@ get: text: type: string example: "Climate Change" + description: The label for this subject. taxonomy_name: type: string example: "OSF" + description: The taxonomy this subject belongs to. relationships: type: object properties: @@ -77,6 +80,7 @@ get: type: type: string example: "subjects" + description: The parent subject, if any. children: type: object properties: @@ -91,6 +95,7 @@ get: type: type: string example: "subjects" + description: Array of child subjects. links: type: object properties: @@ -109,15 +114,16 @@ get: total: type: integer example: 100 + description: Total number of subjects. per_page: type: integer example: 10 + description: Number of results per page. page: type: integer example: 1 + description: Current page number. '400': - description: Bad request (e.g., invalid filter or pagination params) + description: Bad request (e.g., invalid filter or pagination parameters) security: - osf_cookie: [] - produces: - - application/vnd.api+json \ No newline at end of file diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 00874c0..a15ebb3 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -1755,10 +1755,10 @@ paths: ####################################### /custom_file_metadata_records/{file_id}/: - $ref: 'cedar_metadata/files_list.yaml' + $ref: 'custom_metadata/files_list.yaml' - /custom_item_metadata_records/{node_id}/: - $ref: 'cedar_metadata/nodes_list.yaml' + /custom_item_metadata_records/{guid_id}/: + $ref: 'custom_metadata/nodes_list.yaml' ################################ # NOTIFICATION SUBSCRIPTIONS # From ba3e9c23df1bcb9109eadaa7959bd8b8d996efb0 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Fri, 28 Mar 2025 09:17:14 -0400 Subject: [PATCH 19/21] remove cookie info --- swagger-spec/cedar_metadata/files_list.yaml | 3 +-- swagger-spec/cedar_metadata/nodes_list.yaml | 3 +-- .../collection_providers/provider_moderator_detail.yaml | 2 -- .../collection_providers/provider_moderator_list.yaml | 3 --- .../provider_taxonomies_highlighted_list.yaml | 2 -- .../collection_providers/provider_taxonomies_list.yaml | 3 --- swagger-spec/custom_metadata/files_list.yaml | 7 ++----- swagger-spec/institutions/relationships_nodes.yaml | 5 +---- swagger-spec/institutions/relationships_registrations.yaml | 5 +---- swagger-spec/requests/detail.yaml | 2 -- swagger-spec/subjects/children_list.yaml | 3 +-- swagger-spec/subjects/detail.yaml | 2 -- swagger-spec/subjects/list.yaml | 3 +-- swagger-spec/wikis/versions_content_list.yaml | 3 +-- swagger-spec/wikis/versions_detail.yaml | 3 +-- 15 files changed, 10 insertions(+), 39 deletions(-) diff --git a/swagger-spec/cedar_metadata/files_list.yaml b/swagger-spec/cedar_metadata/files_list.yaml index f0e13c8..e3cb1a2 100644 --- a/swagger-spec/cedar_metadata/files_list.yaml +++ b/swagger-spec/cedar_metadata/files_list.yaml @@ -35,5 +35,4 @@ post: description: You do not have permission to create metadata for this file. '404': description: File not found. - security: - - osf_cookie: [] + diff --git a/swagger-spec/cedar_metadata/nodes_list.yaml b/swagger-spec/cedar_metadata/nodes_list.yaml index 4dcb71c..b0753d0 100644 --- a/swagger-spec/cedar_metadata/nodes_list.yaml +++ b/swagger-spec/cedar_metadata/nodes_list.yaml @@ -35,5 +35,4 @@ post: description: You do not have permission to create metadata for this node. '404': description: Node not found. - security: - - osf_cookie: [] + diff --git a/swagger-spec/collection_providers/provider_moderator_detail.yaml b/swagger-spec/collection_providers/provider_moderator_detail.yaml index 7333919..9deda90 100644 --- a/swagger-spec/collection_providers/provider_moderator_detail.yaml +++ b/swagger-spec/collection_providers/provider_moderator_detail.yaml @@ -42,6 +42,4 @@ get: '404': description: Moderator or collection provider not found. - security: - - CookieAuth: [] diff --git a/swagger-spec/collection_providers/provider_moderator_list.yaml b/swagger-spec/collection_providers/provider_moderator_list.yaml index 1c920a7..6395d7d 100644 --- a/swagger-spec/collection_providers/provider_moderator_list.yaml +++ b/swagger-spec/collection_providers/provider_moderator_list.yaml @@ -41,6 +41,3 @@ get: description: You do not have permission to view moderators for this provider. '404': description: Collection provider not found. - - security: - - CookieAuth: [] diff --git a/swagger-spec/collection_providers/provider_taxonomies_highlighted_list.yaml b/swagger-spec/collection_providers/provider_taxonomies_highlighted_list.yaml index 7bcd638..22220b8 100644 --- a/swagger-spec/collection_providers/provider_taxonomies_highlighted_list.yaml +++ b/swagger-spec/collection_providers/provider_taxonomies_highlighted_list.yaml @@ -44,5 +44,3 @@ get: '404': description: Collection provider not found. - security: - - CookieAuth: [] diff --git a/swagger-spec/collection_providers/provider_taxonomies_list.yaml b/swagger-spec/collection_providers/provider_taxonomies_list.yaml index 846b3db..2d90292 100644 --- a/swagger-spec/collection_providers/provider_taxonomies_list.yaml +++ b/swagger-spec/collection_providers/provider_taxonomies_list.yaml @@ -54,6 +54,3 @@ get: '404': description: Collection provider not found. - - security: - - CookieAuth: [] diff --git a/swagger-spec/custom_metadata/files_list.yaml b/swagger-spec/custom_metadata/files_list.yaml index 95db474..534dda8 100644 --- a/swagger-spec/custom_metadata/files_list.yaml +++ b/swagger-spec/custom_metadata/files_list.yaml @@ -23,8 +23,7 @@ get: description: You do not have permission to access this metadata record. '404': description: Metadata record not found. - security: - - osf_cookie: [] + patch: summary: Update custom file metadata for a file @@ -58,6 +57,4 @@ patch: '403': description: You do not have permission to modify this metadata record. '404': - description: Metadata record not found. - security: - - osf_cookie: [] \ No newline at end of file + description: Metadata record not found. \ No newline at end of file diff --git a/swagger-spec/institutions/relationships_nodes.yaml b/swagger-spec/institutions/relationships_nodes.yaml index 248c9a6..3f7eb96 100644 --- a/swagger-spec/institutions/relationships_nodes.yaml +++ b/swagger-spec/institutions/relationships_nodes.yaml @@ -49,8 +49,6 @@ get: description: You do not have permission to view this institution's nodes. '404': description: Institution not found. - security: - - osf_cookie: [] post: summary: Add node relationships to an institution @@ -103,8 +101,7 @@ post: description: You do not have permission to affiliate these nodes. '404': description: Institution not found. - security: - - osf_cookie: [] + delete: summary: Remove node relationships from an institution diff --git a/swagger-spec/institutions/relationships_registrations.yaml b/swagger-spec/institutions/relationships_registrations.yaml index 2dc1872..706b77b 100644 --- a/swagger-spec/institutions/relationships_registrations.yaml +++ b/swagger-spec/institutions/relationships_registrations.yaml @@ -49,8 +49,6 @@ get: description: You do not have permission to view this institution's registrations. '404': description: Institution not found. - security: - - osf_cookie: [] post: summary: Add registration relationships to an institution @@ -103,8 +101,7 @@ post: description: You do not have permission to affiliate these registrations. '404': description: Institution not found. - security: - - osf_cookie: [] + delete: summary: Remove registration relationships from an institution diff --git a/swagger-spec/requests/detail.yaml b/swagger-spec/requests/detail.yaml index 89b2ef0..8a87532 100644 --- a/swagger-spec/requests/detail.yaml +++ b/swagger-spec/requests/detail.yaml @@ -134,5 +134,3 @@ get: description: You do not have permission to view this request. '404': description: Request not found. - security: - - osf_cookie: [] diff --git a/swagger-spec/subjects/children_list.yaml b/swagger-spec/subjects/children_list.yaml index aef5484..27f8878 100644 --- a/swagger-spec/subjects/children_list.yaml +++ b/swagger-spec/subjects/children_list.yaml @@ -117,5 +117,4 @@ get: description: Current page number. '404': description: Parent subject not found. - security: - - osf_cookie: [] + diff --git a/swagger-spec/subjects/detail.yaml b/swagger-spec/subjects/detail.yaml index 0aed397..85025ca 100644 --- a/swagger-spec/subjects/detail.yaml +++ b/swagger-spec/subjects/detail.yaml @@ -93,5 +93,3 @@ get: description: Canonical link to this subject resource. '404': description: Subject not found. - security: - - osf_cookie: [] diff --git a/swagger-spec/subjects/list.yaml b/swagger-spec/subjects/list.yaml index 9659fce..d773625 100644 --- a/swagger-spec/subjects/list.yaml +++ b/swagger-spec/subjects/list.yaml @@ -125,5 +125,4 @@ get: description: Current page number. '400': description: Bad request (e.g., invalid filter or pagination parameters) - security: - - osf_cookie: [] + diff --git a/swagger-spec/wikis/versions_content_list.yaml b/swagger-spec/wikis/versions_content_list.yaml index 1e26640..d6c0311 100644 --- a/swagger-spec/wikis/versions_content_list.yaml +++ b/swagger-spec/wikis/versions_content_list.yaml @@ -41,5 +41,4 @@ get: description: You do not have permission to view this wiki version content. '404': description: Wiki version not found. - security: - - osf_cookie: [] + diff --git a/swagger-spec/wikis/versions_detail.yaml b/swagger-spec/wikis/versions_detail.yaml index 4f54695..a7d2a0f 100644 --- a/swagger-spec/wikis/versions_detail.yaml +++ b/swagger-spec/wikis/versions_detail.yaml @@ -53,5 +53,4 @@ get: description: You do not have permission to view this wiki version. '404': description: Wiki version not found. - security: - - osf_cookie: [] + From 3176ef527081f80c0b61aed9239a5dda514e7771 Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Fri, 28 Mar 2025 09:23:36 -0400 Subject: [PATCH 20/21] add ` - Registration Providers` section --- swagger-spec/swagger.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 729be65..5acd1e4 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -60,6 +60,7 @@ x-tagGroups: - Preprint Providers - Draft Registrations - Registrations + - Registration Providers - Regions - OAuth Scopes - Taxonomies From 33cc67084a0b70aeb3f3740c44f938c871342d8a Mon Sep 17 00:00:00 2001 From: John Tordoff Date: Mon, 31 Mar 2025 16:10:35 -0400 Subject: [PATCH 21/21] clean up OSF resource code --- swagger-spec/nodes/identifiers_list.yaml | 8 ++++---- swagger-spec/nodes/linked_by_nodes_list.yaml | 8 ++++---- .../nodes/linked_by_registrations_list.yaml | 8 ++++---- swagger-spec/nodes/node_settings_list.yaml | 16 ++++++++-------- swagger-spec/nodes/node_storage_list.yaml | 6 +++--- .../nodes/relationships_institutions_list.yaml | 16 ++++++++-------- .../nodes/relationships_linked_nodes_list.yaml | 4 ++-- .../relationships_linked_registrations_list.yaml | 6 +++--- .../nodes/relationships_subjects_list.yaml | 4 ++-- swagger-spec/nodes/requests_list.yaml | 8 ++++---- swagger-spec/nodes/subjects_list.yaml | 6 +++--- .../preprints/files_osfstorage_list.yaml | 4 ++-- swagger-spec/preprints/files_providers_list.yaml | 4 ++-- swagger-spec/preprints/identifiers_list.yaml | 4 ++-- swagger-spec/preprints/relationships_node.yaml | 4 ++-- swagger-spec/registrations/actions_list.yaml | 10 +++++----- .../bibliographic_contributors_list.yaml | 8 ++++---- .../cedar_metadata_records_list.yaml | 8 ++++---- .../implicit_contributors_list.yaml | 8 ++++---- .../registrations/linked_by_nodes_list.yaml | 8 ++++---- .../linked_by_registrations_list.yaml | 8 ++++---- swagger-spec/registrations/node_links_list.yaml | 8 ++++---- .../registrations/registrations_list.yaml | 8 ++++---- .../relationships_institutions_list.yaml | 8 ++++---- .../relationships_linked_nodes_list.yaml | 8 ++++---- .../relationships_linked_registrations_list.yaml | 8 ++++---- .../relationships_subjects_list.yaml | 8 ++++---- swagger-spec/registrations/requests_list.yaml | 10 +++++----- swagger-spec/registrations/resources_list.yaml | 8 ++++---- .../registrations/schema_responses_list.yaml | 8 ++++---- swagger-spec/registrations/subjects_list.yaml | 8 ++++---- .../collection_provider_subscription_detail.yaml | 6 +++--- 32 files changed, 122 insertions(+), 122 deletions(-) diff --git a/swagger-spec/nodes/identifiers_list.yaml b/swagger-spec/nodes/identifiers_list.yaml index b75c357..99c2602 100644 --- a/swagger-spec/nodes/identifiers_list.yaml +++ b/swagger-spec/nodes/identifiers_list.yaml @@ -24,13 +24,13 @@ get: **Example:** Supported filter categories include: - - `doi` - Digital Object Identifier - - `ark` - Archival Resource Key + - `doi` - Digital Object Identifier + - `ark` - Archival Resource Key #### Permissions - - This endpoint is public for nodes that are public. - - Authentication is required to access identifiers on private nodes, and the authenticated user must have read access. + - This endpoint is public for nodes that are public. + - Authentication is required to access identifiers on private nodes, and the authenticated user must have read access. parameters: - in: path diff --git a/swagger-spec/nodes/linked_by_nodes_list.yaml b/swagger-spec/nodes/linked_by_nodes_list.yaml index c925b89..0e73d8b 100644 --- a/swagger-spec/nodes/linked_by_nodes_list.yaml +++ b/swagger-spec/nodes/linked_by_nodes_list.yaml @@ -4,12 +4,12 @@ Retrieve a list of nodes that link to the specified node. #### Permissions - - Public nodes are visible to everyone. - - Private nodes require appropriate permissions to access. - - The authenticated user must have read access to see restricted nodes linking to this node. + - Public nodes are visible to everyone. + - Private nodes require appropriate permissions to access. + - The authenticated user must have read access to see restricted nodes linking to this node. #### Returns - - A paginated list of nodes that link to the specified node. + - A paginated list of nodes that link to the specified node. tags: - Nodes diff --git a/swagger-spec/nodes/linked_by_registrations_list.yaml b/swagger-spec/nodes/linked_by_registrations_list.yaml index 443b168..2e1aff4 100644 --- a/swagger-spec/nodes/linked_by_registrations_list.yaml +++ b/swagger-spec/nodes/linked_by_registrations_list.yaml @@ -4,12 +4,12 @@ get: Retrieve a list of registrations that have created links to the specified node. #### Permissions - - Public registrations are visible to everyone. - - Registrations with restricted visibility require appropriate permissions to access. - - The authenticated user must have read access to see restricted registrations linking to this node. + - Public registrations are visible to everyone. + - Registrations with restricted visibility require appropriate permissions to access. + - The authenticated user must have read access to see restricted registrations linking to this node. #### Returns - - A paginated list of registrations that link to the specified node. + - A paginated list of registrations that link to the specified node. tags: - Nodes diff --git a/swagger-spec/nodes/node_settings_list.yaml b/swagger-spec/nodes/node_settings_list.yaml index 52fae9f..10dafda 100644 --- a/swagger-spec/nodes/node_settings_list.yaml +++ b/swagger-spec/nodes/node_settings_list.yaml @@ -5,11 +5,11 @@ get: This includes details such as whether wiki functionality is enabled, if comments are enabled, and other configurable settings. #### Permissions - - Public nodes expose a subset of settings. - - Private nodes require read permissions to view full settings. + - Public nodes expose a subset of settings. + - Private nodes require read permissions to view full settings. #### Returns - - A JSON object with a `data` key containing the node's settings. + - A JSON object with a `data` key containing the node's settings. tags: - Nodes @@ -94,13 +94,13 @@ patch: - Only users with write access to the node can modify its settings. #### Request Body - - The `attributes` object may include the following fields: - - `wiki_enabled`: Enable or disable the node's wiki. - - `comments_enabled`: Enable or disable comments on the node. - - `public`: Make the node public or private. + - The `attributes` object may include the following fields: + - `wiki_enabled`: Enable or disable the node's wiki. + - `comments_enabled`: Enable or disable comments on the node. + - `public`: Make the node public or private. #### Returns - - A JSON object with the updated node settings under the `data` key. + - A JSON object with the updated node settings under the `data` key. tags: - Nodes diff --git a/swagger-spec/nodes/node_storage_list.yaml b/swagger-spec/nodes/node_storage_list.yaml index 00ee102..0923c1d 100644 --- a/swagger-spec/nodes/node_storage_list.yaml +++ b/swagger-spec/nodes/node_storage_list.yaml @@ -5,11 +5,11 @@ get: Each node in the OSF automatically has an OSF Storage provider, and may have additional third-party storage providers (such as Dropbox or Google Drive) if configured. #### Permissions - - Public nodes expose storage provider information publicly. - - Private nodes require read permissions to access storage providers. + - Public nodes expose storage provider information publicly. + - Private nodes require read permissions to access storage providers. #### Returns - - A JSON object with a `data` array containing storage provider resources assigned to the node. + - A JSON object with a `data` array containing storage provider resources assigned to the node. tags: - Nodes diff --git a/swagger-spec/nodes/relationships_institutions_list.yaml b/swagger-spec/nodes/relationships_institutions_list.yaml index c4e078a..13903bd 100644 --- a/swagger-spec/nodes/relationships_institutions_list.yaml +++ b/swagger-spec/nodes/relationships_institutions_list.yaml @@ -4,8 +4,8 @@ get: Retrieve a list of resource identifier objects that represent the institutions affiliated with the given node. #### Permissions - - Public nodes will display their affiliated institutions. - - Private nodes require read permissions. + - Public nodes will display their affiliated institutions. + - Private nodes require read permissions. #### Returns - A JSON object with a `data` key containing an array of resource identifier objects (`type` and `id`) for each affiliated institution. @@ -71,13 +71,13 @@ patch: Replace all existing affiliated institutions for a node with a new set of institutions. #### Permissions - - The authenticated user must have admin permissions on the node. + - The authenticated user must have admin permissions on the node. #### Request Body - - A `data` array containing the new list of institution resource identifier objects (`type` and `id`). + - A `data` array containing the new list of institution resource identifier objects (`type` and `id`). #### Returns - - The updated list of affiliated institutions for the node. + - The updated list of affiliated institutions for the node. tags: - Nodes @@ -150,13 +150,13 @@ post: Add new affiliated institutions to the node, while keeping the existing ones intact. #### Permissions - - The authenticated user must have admin permissions on the node. + - The authenticated user must have admin permissions on the node. #### Request Body - - A `data` array containing additional institution resource identifier objects to be added. + - A `data` array containing additional institution resource identifier objects to be added. #### Returns - - The updated list of affiliated institutions for the node. + - The updated list of affiliated institutions for the node. tags: - Nodes diff --git a/swagger-spec/nodes/relationships_linked_nodes_list.yaml b/swagger-spec/nodes/relationships_linked_nodes_list.yaml index d7974aa..6f40d49 100644 --- a/swagger-spec/nodes/relationships_linked_nodes_list.yaml +++ b/swagger-spec/nodes/relationships_linked_nodes_list.yaml @@ -4,8 +4,8 @@ get: Retrieve a list of resource identifier objects that represent the nodes linked to the given node. #### Permissions - - Public nodes will display their public linked nodes. - - Private nodes require read permissions. + - Public nodes will display their public linked nodes. + - Private nodes require read permissions. #### Returns - A JSON object with a `data` key containing an array of resource identifier objects (`type` and `id`) for each linked node. diff --git a/swagger-spec/nodes/relationships_linked_registrations_list.yaml b/swagger-spec/nodes/relationships_linked_registrations_list.yaml index d9564ff..16e31a0 100644 --- a/swagger-spec/nodes/relationships_linked_registrations_list.yaml +++ b/swagger-spec/nodes/relationships_linked_registrations_list.yaml @@ -4,8 +4,8 @@ get: Retrieve a list of resource identifier objects that represent the registrations linked to the given node. #### Permissions - - Public nodes will show public linked registrations. - - Private nodes require read permissions. + - Public nodes will show public linked registrations. + - Private nodes require read permissions. #### Returns - A JSON object with a `data` key containing an array of resource identifier objects (`type` and `id`) for each linked registration. @@ -71,7 +71,7 @@ patch: Replace all existing linked registrations for a node with a new set of linked registrations. #### Permissions - - The authenticated user must have write permissions on the node. + - The authenticated user must have write permissions on the node. #### Request Body - A `data` array containing the new list of registration resource identifier objects (`type` and `id`). diff --git a/swagger-spec/nodes/relationships_subjects_list.yaml b/swagger-spec/nodes/relationships_subjects_list.yaml index c2bb9d5..2ded313 100644 --- a/swagger-spec/nodes/relationships_subjects_list.yaml +++ b/swagger-spec/nodes/relationships_subjects_list.yaml @@ -4,8 +4,8 @@ get: Retrieve a list of relationship identifiers (resource linkage) representing the subjects associated with a specific node. #### Permissions - - Public nodes will display public subjects. - - Private nodes require read permissions. + - Public nodes will display public subjects. + - Private nodes require read permissions. #### Returns - A JSON object with a `data` key containing an array of resource identifier objects (`type` and `id`) for each subject linked to the node. diff --git a/swagger-spec/nodes/requests_list.yaml b/swagger-spec/nodes/requests_list.yaml index 77ee668..d952711 100644 --- a/swagger-spec/nodes/requests_list.yaml +++ b/swagger-spec/nodes/requests_list.yaml @@ -5,12 +5,12 @@ get: Requests include actions such as registration approval, withdrawal, or other moderation-related requests initiated on the node. #### Permissions - - The authenticated user must have read access to the node to view its requests. - - Moderators or admins of the provider may have additional access to request details depending on their role. + - The authenticated user must have read access to the node to view its requests. + - Moderators or admins of the provider may have additional access to request details depending on their role. #### Returns - - A JSON object with a `data` key containing a list of request resources. - - Each request provides metadata about its current state, type, creator, and review process. + - A JSON object with a `data` key containing a list of request resources. + - Each request provides metadata about its current state, type, creator, and review process. tags: - Nodes diff --git a/swagger-spec/nodes/subjects_list.yaml b/swagger-spec/nodes/subjects_list.yaml index 7de32fe..41fc13d 100644 --- a/swagger-spec/nodes/subjects_list.yaml +++ b/swagger-spec/nodes/subjects_list.yaml @@ -6,11 +6,11 @@ get: A node can have multiple subjects, typically applied in the context of preprints or projects associated with specific disciplines. #### Permissions - - Public nodes expose subjects publicly. - - Private nodes require read permissions to access subjects. + - Public nodes expose subjects publicly. + - Private nodes require read permissions to access subjects. #### Returns - - A JSON object with a `data` array containing subject resources assigned to the node. + - A JSON object with a `data` array containing subject resources assigned to the node. tags: - Nodes diff --git a/swagger-spec/preprints/files_osfstorage_list.yaml b/swagger-spec/preprints/files_osfstorage_list.yaml index 87aba0b..582a6fd 100644 --- a/swagger-spec/preprints/files_osfstorage_list.yaml +++ b/swagger-spec/preprints/files_osfstorage_list.yaml @@ -5,8 +5,8 @@ get: Only "osfstorage" is available for preprints. #### Permissions - - Public files are accessible to unauthenticated users. - - Viewing non-public files requires appropriate permissions. + - Public files are accessible to unauthenticated users. + - Viewing non-public files requires appropriate permissions. tags: - Preprints diff --git a/swagger-spec/preprints/files_providers_list.yaml b/swagger-spec/preprints/files_providers_list.yaml index 4a8da5a..dc19a6d 100644 --- a/swagger-spec/preprints/files_providers_list.yaml +++ b/swagger-spec/preprints/files_providers_list.yaml @@ -5,8 +5,8 @@ get: Only "osfstorage" is supported for preprints. #### Permissions - - Public storage providers are accessible to unauthenticated users. - - Viewing non-public preprints requires appropriate permissions. + - Public storage providers are accessible to unauthenticated users. + - Viewing non-public preprints requires appropriate permissions. tags: - Preprints diff --git a/swagger-spec/preprints/identifiers_list.yaml b/swagger-spec/preprints/identifiers_list.yaml index cf0d48e..4389540 100644 --- a/swagger-spec/preprints/identifiers_list.yaml +++ b/swagger-spec/preprints/identifiers_list.yaml @@ -5,8 +5,8 @@ get: Identifiers include DOIs, ARKs, and other unique resource locators. #### Permissions - - Public identifiers are accessible to unauthenticated users. - - Private preprints require read access to view their identifiers. + - Public identifiers are accessible to unauthenticated users. + - Private preprints require read access to view their identifiers. tags: - Preprints diff --git a/swagger-spec/preprints/relationships_node.yaml b/swagger-spec/preprints/relationships_node.yaml index c08804e..5cef0ac 100644 --- a/swagger-spec/preprints/relationships_node.yaml +++ b/swagger-spec/preprints/relationships_node.yaml @@ -4,8 +4,8 @@ get: Retrieve a relationship object that points to the supplemental node associated with this preprint. #### Permissions - - Public preprints will return their supplemental node if it exists. - - Private preprints require the user to have read access. + - Public preprints will return their supplemental node if it exists. + - Private preprints require the user to have read access. tags: - Preprints diff --git a/swagger-spec/registrations/actions_list.yaml b/swagger-spec/registrations/actions_list.yaml index 13a992a..dd63337 100644 --- a/swagger-spec/registrations/actions_list.yaml +++ b/swagger-spec/registrations/actions_list.yaml @@ -5,13 +5,13 @@ get: or moderation events, such as submission, approval, rejection, and withdrawal requests. #### Permissions - - Publicly accessible if the registration is public. - - Administrators of the registration always have access. - - Moderators of the associated Registration Provider may have access depending on action type. + - Publicly accessible if the registration is public. + - Administrators of the registration always have access. + - Moderators of the associated Registration Provider may have access depending on action type. #### Returns - - A JSON object containing a list of `registration actions` returned in a `data` array. - - Each action describes a specific event or state transition applied to the registration. + - A JSON object containing a list of `registration actions` returned in a `data` array. + - Each action describes a specific event or state transition applied to the registration. tags: - Registrations diff --git a/swagger-spec/registrations/bibliographic_contributors_list.yaml b/swagger-spec/registrations/bibliographic_contributors_list.yaml index 9eadc03..d4ebc69 100644 --- a/swagger-spec/registrations/bibliographic_contributors_list.yaml +++ b/swagger-spec/registrations/bibliographic_contributors_list.yaml @@ -7,14 +7,14 @@ get: These contributors appear in citations and are considered authors on the registration's public pages and metadata. #### Permissions - - Public registrations expose bibliographic contributors publicly. - - Private registrations require appropriate read permissions to view bibliographic contributors. + - Public registrations expose bibliographic contributors publicly. + - Private registrations require appropriate read permissions to view bibliographic contributors. #### Returns - - A JSON object with a `data` array containing contributor resources that are marked as bibliographic for the registration. + - A JSON object with a `data` array containing contributor resources that are marked as bibliographic for the registration. tags: - - Registration + - Registrations operationId: registration_bibliographic_contributors_list diff --git a/swagger-spec/registrations/cedar_metadata_records_list.yaml b/swagger-spec/registrations/cedar_metadata_records_list.yaml index e7de47b..b1897e2 100644 --- a/swagger-spec/registrations/cedar_metadata_records_list.yaml +++ b/swagger-spec/registrations/cedar_metadata_records_list.yaml @@ -7,14 +7,14 @@ get: Each record corresponds to a specific metadata schema provided by the CEDAR system and enhances the discoverability and documentation of a registration. #### Permissions - - Public registrations expose their CEDAR metadata records publicly. - - Private registrations require appropriate read permissions to view CEDAR metadata records. + - Public registrations expose their CEDAR metadata records publicly. + - Private registrations require appropriate read permissions to view CEDAR metadata records. #### Returns - - A JSON object with a `data` array containing CEDAR metadata records related to the registration. + - A JSON object with a `data` array containing CEDAR metadata records related to the registration. tags: - - Registration + - Registrations operationId: registration_cedar_metadata_records_list diff --git a/swagger-spec/registrations/implicit_contributors_list.yaml b/swagger-spec/registrations/implicit_contributors_list.yaml index 450fa62..4e8ee19 100644 --- a/swagger-spec/registrations/implicit_contributors_list.yaml +++ b/swagger-spec/registrations/implicit_contributors_list.yaml @@ -7,14 +7,14 @@ get: are inherited by this registration. They are not explicitly listed as contributors but have an implied relationship. #### Permissions - - Public registrations expose their implicit contributors publicly. - - Private registrations require appropriate read permissions to view contributors. + - Public registrations expose their implicit contributors publicly. + - Private registrations require appropriate read permissions to view contributors. #### Returns - - A JSON object containing a `data` array of user resources representing implicit contributors to the registration. + - A JSON object containing a `data` array of user resources representing implicit contributors to the registration. tags: - - Registration + - Registrations operationId: registration_implicit_contributors_list diff --git a/swagger-spec/registrations/linked_by_nodes_list.yaml b/swagger-spec/registrations/linked_by_nodes_list.yaml index 4f0dce6..7578cbf 100644 --- a/swagger-spec/registrations/linked_by_nodes_list.yaml +++ b/swagger-spec/registrations/linked_by_nodes_list.yaml @@ -6,14 +6,14 @@ get: This endpoint allows you to discover which nodes are referencing the given registration by including it in their node links. #### Permissions - - Public registrations expose their linked by nodes publicly. - - Private registrations require appropriate read permissions to view this relationship. + - Public registrations expose their linked by nodes publicly. + - Private registrations require appropriate read permissions to view this relationship. #### Returns - - A JSON object containing a `data` array of node resources that link to the specified registration. + - A JSON object containing a `data` array of node resources that link to the specified registration. tags: - - Registration + - Registrations operationId: registration_linked_by_nodes_list diff --git a/swagger-spec/registrations/linked_by_registrations_list.yaml b/swagger-spec/registrations/linked_by_registrations_list.yaml index 761b93c..ff2a11d 100644 --- a/swagger-spec/registrations/linked_by_registrations_list.yaml +++ b/swagger-spec/registrations/linked_by_registrations_list.yaml @@ -6,14 +6,14 @@ get: This allows you to discover which registrations are referencing the given registration through their node links. #### Permissions - - Public registrations expose their linked by registrations publicly. - - Private registrations require read access to view this relationship. + - Public registrations expose their linked by registrations publicly. + - Private registrations require read access to view this relationship. #### Returns - - A JSON object containing a `data` array of registration resources that link to this registration. + - A JSON object containing a `data` array of registration resources that link to this registration. tags: - - Registration + - Registrations operationId: registration_linked_by_registrations_list diff --git a/swagger-spec/registrations/node_links_list.yaml b/swagger-spec/registrations/node_links_list.yaml index 949ebb1..ee5e690 100644 --- a/swagger-spec/registrations/node_links_list.yaml +++ b/swagger-spec/registrations/node_links_list.yaml @@ -7,14 +7,14 @@ get: They allow users to create a relationship between a registration and other nodes within OSF. #### Permissions - - Public registrations expose their node links publicly. - - Private registrations require read access to view node links. + - Public registrations expose their node links publicly. + - Private registrations require read access to view node links. #### Returns - - A JSON object containing a `data` array with node link resources. + - A JSON object containing a `data` array with node link resources. tags: - - Registration + - Registrations operationId: registration_node_links_list diff --git a/swagger-spec/registrations/registrations_list.yaml b/swagger-spec/registrations/registrations_list.yaml index 1554e5f..c7b38e6 100644 --- a/swagger-spec/registrations/registrations_list.yaml +++ b/swagger-spec/registrations/registrations_list.yaml @@ -7,14 +7,14 @@ get: This endpoint returns all registrations that are children of the given parent registration. #### Permissions - - Public registrations will display their children publicly. - - Private registrations require appropriate permissions to view child registrations. + - Public registrations will display their children publicly. + - Private registrations require appropriate permissions to view child registrations. #### Returns - - A JSON object with a `data` key containing a list of child registration resources. + - A JSON object with a `data` key containing a list of child registration resources. tags: - - Registration + - Registrations operationId: registrations_children_list diff --git a/swagger-spec/registrations/relationships_institutions_list.yaml b/swagger-spec/registrations/relationships_institutions_list.yaml index 12e5698..a1a4d08 100644 --- a/swagger-spec/registrations/relationships_institutions_list.yaml +++ b/swagger-spec/registrations/relationships_institutions_list.yaml @@ -7,14 +7,14 @@ get: To retrieve detailed information about these institutions, use the `related` link or query the `/institutions/` endpoint. #### Permissions - - Public registrations will display their institutions publicly. - - Private registrations require appropriate permissions to view affiliated institutions. + - Public registrations will display their institutions publicly. + - Private registrations require appropriate permissions to view affiliated institutions. #### Returns - - A JSON object with a `data` key, containing an array of `institutions` resource identifier objects (`id` and `type`). + - A JSON object with a `data` key, containing an array of `institutions` resource identifier objects (`id` and `type`). tags: - - Registration + - Registrations operationId: relationships_institutions_list diff --git a/swagger-spec/registrations/relationships_linked_nodes_list.yaml b/swagger-spec/registrations/relationships_linked_nodes_list.yaml index ff1f6e9..f975c73 100644 --- a/swagger-spec/registrations/relationships_linked_nodes_list.yaml +++ b/swagger-spec/registrations/relationships_linked_nodes_list.yaml @@ -10,14 +10,14 @@ get: or follow the `related` link provided in this response. #### Permissions - - Public nodes/registrations expose linked nodes publicly. - - Private nodes/registrations require appropriate permissions to view their linked nodes. + - Public nodes/registrations expose linked nodes publicly. + - Private nodes/registrations require appropriate permissions to view their linked nodes. #### Returns - - A JSON object with a `data` key, containing an array of `nodes` resource identifier objects (`id` and `type`). + - A JSON object with a `data` key, containing an array of `nodes` resource identifier objects (`id` and `type`). tags: - - Registration + - Registrations operationId: relationships_linked_nodes_list diff --git a/swagger-spec/registrations/relationships_linked_registrations_list.yaml b/swagger-spec/registrations/relationships_linked_registrations_list.yaml index 8fd4843..02f53d4 100644 --- a/swagger-spec/registrations/relationships_linked_registrations_list.yaml +++ b/swagger-spec/registrations/relationships_linked_registrations_list.yaml @@ -10,14 +10,14 @@ get: or follow the `related` link provided in this response. #### Permissions - - Public registrations expose linked registrations publicly. - - Private registrations require appropriate permissions to view their linked registrations. + - Public registrations expose linked registrations publicly. + - Private registrations require appropriate permissions to view their linked registrations. #### Returns - - A JSON object with a `data` key, containing an array of `registration` resource identifier objects (`id` and `type`). + - A JSON object with a `data` key, containing an array of `registration` resource identifier objects (`id` and `type`). tags: - - Registration + - Registrations operationId: registration_linked_registrations_relationship_list diff --git a/swagger-spec/registrations/relationships_subjects_list.yaml b/swagger-spec/registrations/relationships_subjects_list.yaml index 216778f..e3da318 100644 --- a/swagger-spec/registrations/relationships_subjects_list.yaml +++ b/swagger-spec/registrations/relationships_subjects_list.yaml @@ -7,14 +7,14 @@ get: To get the full details of the subjects, you should follow the `related` link provided in the relationships object or query the `/registrations/{registration_id}/subjects/` endpoint. #### Permissions - - Public registrations expose this relationship publicly. - - Private registrations require appropriate permissions to view their subjects. + - Public registrations expose this relationship publicly. + - Private registrations require appropriate permissions to view their subjects. #### Returns - - A JSON object with a `data` key, which contains an array of `subject` resource identifier objects (`id` and `type`). + - A JSON object with a `data` key, which contains an array of `subject` resource identifier objects (`id` and `type`). tags: - - Registration + - Registrations operationId: registration_subjects_relationship_list diff --git a/swagger-spec/registrations/requests_list.yaml b/swagger-spec/registrations/requests_list.yaml index a9b5279..3c64483 100644 --- a/swagger-spec/registrations/requests_list.yaml +++ b/swagger-spec/registrations/requests_list.yaml @@ -7,13 +7,13 @@ get: including withdrawal requests, embargo requests, and schema update requests. #### Permissions - - Public registrations expose some request metadata publicly. - - Private registrations require read access for non-admin contributors. - - Only admins and moderators can view and manage sensitive request details. + - Public registrations expose some request metadata publicly. + - Private registrations require read access for non-admin contributors. + - Only admins and moderators can view and manage sensitive request details. #### Returns - - A JSON object with a `data` key containing an array of request records. - - Each request includes the type of request (withdrawal, embargo, etc.), its state, + - A JSON object with a `data` key containing an array of request records. + - Each request includes the type of request (withdrawal, embargo, etc.), its state, and information about who initiated the request. tags: diff --git a/swagger-spec/registrations/resources_list.yaml b/swagger-spec/registrations/resources_list.yaml index d1eb256..0300b6a 100644 --- a/swagger-spec/registrations/resources_list.yaml +++ b/swagger-spec/registrations/resources_list.yaml @@ -7,12 +7,12 @@ get: These resources help provide additional context, background, or supporting materials for the registration. #### Permissions - - Public registrations expose their related resources publicly. - - Private registrations require the user to have read access to view related resources. + - Public registrations expose their related resources publicly. + - Private registrations require the user to have read access to view related resources. #### Returns - - A JSON object with a `data` key containing an array of related resources. - - Related resources may include nodes, preprints, and other OSF resources. + - A JSON object with a `data` key containing an array of related resources. + - Related resources may include nodes, preprints, and other OSF resources. tags: - Registrations diff --git a/swagger-spec/registrations/schema_responses_list.yaml b/swagger-spec/registrations/schema_responses_list.yaml index 3352346..94bebaa 100644 --- a/swagger-spec/registrations/schema_responses_list.yaml +++ b/swagger-spec/registrations/schema_responses_list.yaml @@ -8,12 +8,12 @@ get: A registration can have multiple schema responses over time due to edits or updates, depending on the registration provider's workflow. #### Permissions - - Publicly accessible for public registrations. - - Private registrations require appropriate permissions (must be a contributor with read access). + - Publicly accessible for public registrations. + - Private registrations require appropriate permissions (must be a contributor with read access). #### Returns - - A JSON object with a `data` key containing an array of schema response resources. - - Each schema response includes its current state, related actions, and the data provided in the registration form. + - A JSON object with a `data` key containing an array of schema response resources. + - Each schema response includes its current state, related actions, and the data provided in the registration form. tags: - Registrations diff --git a/swagger-spec/registrations/subjects_list.yaml b/swagger-spec/registrations/subjects_list.yaml index 01623d9..d0aef16 100644 --- a/swagger-spec/registrations/subjects_list.yaml +++ b/swagger-spec/registrations/subjects_list.yaml @@ -7,12 +7,12 @@ get: These subjects help with search, discovery, and classification within the OSF platform. #### Permissions - - Publicly accessible if the registration is public. - - Private registrations require admin permissions to access. + - Publicly accessible if the registration is public. + - Private registrations require admin permissions to access. #### Returns - - A JSON object with a `data` key containing an array of subject resources. - - Each subject describes a taxonomy term, including its name and hierarchical position. + - A JSON object with a `data` key containing an array of subject resources. + - Each subject describes a taxonomy term, including its name and hierarchical position. tags: - Registrations diff --git a/swagger-spec/subscriptions/collection_provider_subscription_detail.yaml b/swagger-spec/subscriptions/collection_provider_subscription_detail.yaml index ab9bd08..4663dac 100644 --- a/swagger-spec/subscriptions/collection_provider_subscription_detail.yaml +++ b/swagger-spec/subscriptions/collection_provider_subscription_detail.yaml @@ -74,9 +74,9 @@ patch: Provide the `frequency` attribute within the `attributes` object to update the subscription. #### Available Frequency Values: - - `instant`: Immediate email notifications. - - `daily`: Daily summary emails. - - `none`: Disable email notifications. + - `instant`: Immediate email notifications. + - `daily`: Daily summary emails. + - `none`: Disable email notifications. #### Returns - A JSON object with the updated subscription details under the `data` key if the update is successful.