From a03d4c3bb2cf81d3aa4f51fac768fd00ede33380 Mon Sep 17 00:00:00 2001 From: Ihor Sokhan Date: Fri, 6 Mar 2026 19:06:50 +0200 Subject: [PATCH 1/5] updated docs for preprint providers --- swagger-spec/nodes/preprints_list.yaml | 2 +- swagger-spec/preprint_providers/detail.yaml | 14 +- swagger-spec/preprint_providers/list.yaml | 18 +- .../moderator_definition.yaml | 4 +- .../preprint_providers/moderators_detail.yaml | 4 +- .../preprint_providers/moderators_list.yaml | 8 +- .../preprint_providers/preprints_list.yaml | 4 +- .../provider_moderator_detail.yaml | 6 +- .../provider_moderator_list.yaml | 10 +- .../provider_subjects_list.yaml | 104 ---------- .../provider_taxonomies_highlighted_list.yaml | 10 +- .../provider_taxonomies_list.yaml | 10 +- .../subjects_highlighted_list.yaml | 84 ++++++++ .../preprint_providers/subjects_list.yaml | 191 ++++++++++++++---- swagger-spec/preprints/list.yaml | 2 +- swagger-spec/swagger.yaml | 23 ++- swagger-spec/users/preprints_list.yaml | 2 +- 17 files changed, 304 insertions(+), 192 deletions(-) delete mode 100644 swagger-spec/preprint_providers/provider_subjects_list.yaml diff --git a/swagger-spec/nodes/preprints_list.yaml b/swagger-spec/nodes/preprints_list.yaml index ffbebad..37d6994 100644 --- a/swagger-spec/nodes/preprints_list.yaml +++ b/swagger-spec/nodes/preprints_list.yaml @@ -58,7 +58,7 @@ get: provider: links: related: - href: https://api.osf.io/v2/preprint_providers/osf/ + href: https://api.osf.io/v2/providers/preprints/osf/ meta: {} links: self: https://api.osf.io/v2/preprints/khbvy/ diff --git a/swagger-spec/preprint_providers/detail.yaml b/swagger-spec/preprint_providers/detail.yaml index e584ec2..ec4dbce 100644 --- a/swagger-spec/preprint_providers/detail.yaml +++ b/swagger-spec/preprint_providers/detail.yaml @@ -84,28 +84,28 @@ get: licenses_acceptable: links: related: - href: https://api.osf.io/v2/preprint_providers/osf/licenses/ + href: https://api.osf.io/v2/providers/preprints/osf/licenses/ meta: {} taxonomies: links: related: - href: https://api.osf.io/v2/preprint_providers/osf/taxonomies/ + href: https://api.osf.io/v2/providers/preprints/osf/taxonomies/ meta: {} preprints: links: related: - href: https://api.osf.io/v2/preprint_providers/osf/preprints/ + href: https://api.osf.io/v2/providers/preprints/osf/preprints/ meta: {} links: - self: https://api.osf.io/v2/preprint_providers/osf/ - preprints: https://api.osf.io/v2/preprint_providers/osf/preprints/ + self: https://api.osf.io/v2/providers/preprints/osf/ + preprints: https://api.osf.io/v2/providers/preprints/osf/preprints/ external_url: https://osf.io/preprints/ attributes: social_instagram: '' advisory_board: '' email_support: '' - banner_path: "/static/img/preprint_providers/cos-logo.png" - logo_path: "/static/img/preprint_providers/cos-logo.png" + banner_path: "/static/img/providers/preprints/cos-logo.png" + logo_path: "/static/img/providers/preprints/cos-logo.png" subjects_acceptable: [] description: A scholarly commons to connect the entire research cycle social_facebook: '' diff --git a/swagger-spec/preprint_providers/list.yaml b/swagger-spec/preprint_providers/list.yaml index a0f3b9b..c07a3db 100644 --- a/swagger-spec/preprint_providers/list.yaml +++ b/swagger-spec/preprint_providers/list.yaml @@ -1,4 +1,4 @@ -# /preprint_providers/ +# /providers/preprints/ get: summary: List all preprint providers description: >- @@ -26,7 +26,7 @@ get: 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/preprint_providers/?filter[id]=osf. + https://api.osf.io/v2/providers/preprints/?filter[id]=osf. Preprint Providers may be filtered by their `id`, `name`, and `description` @@ -47,28 +47,28 @@ get: licenses_acceptable: links: related: - href: https://api.osf.io/v2/preprint_providers/osf/licenses/ + href: https://api.osf.io/v2/providers/preprints/osf/licenses/ meta: {} taxonomies: links: related: - href: https://api.osf.io/v2/preprint_providers/osf/taxonomies/ + href: https://api.osf.io/v2/providers/preprints/osf/taxonomies/ meta: {} preprints: links: related: - href: https://api.osf.io/v2/preprint_providers/osf/preprints/ + href: https://api.osf.io/v2/providers/preprints/osf/preprints/ meta: {} links: - self: https://api.osf.io/v2/preprint_providers/osf/ - preprints: https://api.osf.io/v2/preprint_providers/osf/preprints/ + self: https://api.osf.io/v2/providers/preprints/osf/ + preprints: https://api.osf.io/v2/providers/preprints/osf/preprints/ external_url: https://osf.io/preprints/ attributes: social_instagram: '' advisory_board: '' email_support: '' - banner_path: "/static/img/preprint_providers/cos-logo.png" - logo_path: "/static/img/preprint_providers/cos-logo.png" + banner_path: "/static/img/providers/preprints/cos-logo.png" + logo_path: "/static/img/providers/preprints/cos-logo.png" subjects_acceptable: [] description: A scholarly commons to connect the entire research cycle social_facebook: '' diff --git a/swagger-spec/preprint_providers/moderator_definition.yaml b/swagger-spec/preprint_providers/moderator_definition.yaml index b5828f0..80aaac3 100644 --- a/swagger-spec/preprint_providers/moderator_definition.yaml +++ b/swagger-spec/preprint_providers/moderator_definition.yaml @@ -80,7 +80,7 @@ properties: 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: https://api.test.osf.io/v2/providers/preprints/provider_1/moderators/moderator_1/ example: id: moderator_1 type: moderators @@ -95,4 +95,4 @@ example: type: preprint_providers id: provider_1 links: - self: https://api.test.osf.io/v2/preprint_providers/provider_1/moderators/moderator_1/ + self: https://api.test.osf.io/v2/providers/preprints/provider_1/moderators/moderator_1/ diff --git a/swagger-spec/preprint_providers/moderators_detail.yaml b/swagger-spec/preprint_providers/moderators_detail.yaml index 99649ac..a419908 100644 --- a/swagger-spec/preprint_providers/moderators_detail.yaml +++ b/swagger-spec/preprint_providers/moderators_detail.yaml @@ -1,4 +1,4 @@ -# /preprint_providers/{provider_id}/moderators/{moderator_id}/ +# /providers/preprints/{provider_id}/moderators/{moderator_id}/ get: summary: Retrieve a Preprint Provider Moderator @@ -51,7 +51,7 @@ get: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/{moderator_id}/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/{moderator_id}/" meta: version: "2.0" '401': diff --git a/swagger-spec/preprint_providers/moderators_list.yaml b/swagger-spec/preprint_providers/moderators_list.yaml index a331601..a598899 100644 --- a/swagger-spec/preprint_providers/moderators_list.yaml +++ b/swagger-spec/preprint_providers/moderators_list.yaml @@ -1,4 +1,4 @@ -# /preprint_providers/{provider_id}/moderators/ +# /providers/preprints/{provider_id}/moderators/ get: summary: List Moderators for a Preprint Provider @@ -49,7 +49,7 @@ get: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_1/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/moderator_1/" - id: "moderator_2" type: "moderators" attributes: @@ -63,7 +63,7 @@ get: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_2/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/moderator_2/" meta: total: 2 version: "2.0" @@ -168,7 +168,7 @@ post: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_3/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/moderator_3/" meta: version: "2.0" '400': diff --git a/swagger-spec/preprint_providers/preprints_list.yaml b/swagger-spec/preprint_providers/preprints_list.yaml index 9c6a4fc..36ce56b 100644 --- a/swagger-spec/preprint_providers/preprints_list.yaml +++ b/swagger-spec/preprint_providers/preprints_list.yaml @@ -28,7 +28,7 @@ get: You can optionally request that the response only include preprints that match your filters by utilizing the `filter` query parameter, e.g. - https://api.osf.io/v2/preprint_providers/osf/preprints/?filter[is_published]=true. + https://api.osf.io/v2/providers/preprints/osf/preprints/?filter[is_published]=true. Preprints may be filtered by their `id`, `is_published`, `date_created`, @@ -77,7 +77,7 @@ get: provider: links: related: - href: 'https://api.osf.io/v2/preprint_providers/socarxiv/' + href: 'https://api.osf.io/v2/providers/preprints/socarxiv/' meta: {} links: self: 'https://api.osf.io/v2/preprints/hqb2p/' diff --git a/swagger-spec/preprint_providers/provider_moderator_detail.yaml b/swagger-spec/preprint_providers/provider_moderator_detail.yaml index fc2a1d6..af2e989 100644 --- a/swagger-spec/preprint_providers/provider_moderator_detail.yaml +++ b/swagger-spec/preprint_providers/provider_moderator_detail.yaml @@ -1,4 +1,4 @@ -# /preprint_providers/{provider_id}/moderators/{moderator_id}/ +# /providers/preprints/{provider_id}/moderators/{moderator_id}/ get: summary: Retrieve a Moderator for a Preprint Provider @@ -51,7 +51,7 @@ get: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_1/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/moderator_1/" meta: version: "2.0" '401': @@ -162,7 +162,7 @@ patch: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_1/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/moderator_1/" meta: version: "2.0" '400': diff --git a/swagger-spec/preprint_providers/provider_moderator_list.yaml b/swagger-spec/preprint_providers/provider_moderator_list.yaml index 56bd4c6..a65909d 100644 --- a/swagger-spec/preprint_providers/provider_moderator_list.yaml +++ b/swagger-spec/preprint_providers/provider_moderator_list.yaml @@ -1,4 +1,4 @@ -# /preprint_providers/{provider_id}/moderators/ +# /providers/preprints/{provider_id}/moderators/ get: summary: List Moderators for a Preprint Provider @@ -77,7 +77,7 @@ get: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_1/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/moderator_1/" - id: "moderator_2" type: "moderators" attributes: @@ -91,9 +91,9 @@ get: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_2/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/moderator_2/" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/" next: null prev: null meta: @@ -224,7 +224,7 @@ post: type: "preprint_providers" id: "{provider_id}" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/moderators/moderator_3/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/moderators/moderator_3/" meta: version: "2.0" diff --git a/swagger-spec/preprint_providers/provider_subjects_list.yaml b/swagger-spec/preprint_providers/provider_subjects_list.yaml deleted file mode 100644 index 7ae814b..0000000 --- a/swagger-spec/preprint_providers/provider_subjects_list.yaml +++ /dev/null @@ -1,104 +0,0 @@ -# /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 index 3cd1f98..d8625e7 100644 --- a/swagger-spec/preprint_providers/provider_taxonomies_highlighted_list.yaml +++ b/swagger-spec/preprint_providers/provider_taxonomies_highlighted_list.yaml @@ -1,12 +1,14 @@ -# /preprint_providers/{provider_id}/taxonomies/highlighted/ +# /providers/preprints/{provider_id}/taxonomies/highlighted/ get: - summary: List Highlighted Taxonomies for a Preprint Provider + summary: List Highlighted Taxonomies for a Preprint Provider (Deprecated) 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. + **Deprecated:** Use the `highlighted subjects` endpoint instead. + #### Permissions - No authentication required for public providers. - Only authorized users can access restricted providers. @@ -15,6 +17,8 @@ get: - A JSON object with a `data` key containing an array of taxonomy resources. - Each taxonomy represents a subject that can be assigned to preprints. + deprecated: true + tags: - Preprint Providers - Taxonomies @@ -73,7 +77,7 @@ get: links: self: "https://api.test.osf.io/v2/taxonomies/psychology/" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/taxonomies/highlighted/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/taxonomies/highlighted/" next: null prev: null meta: diff --git a/swagger-spec/preprint_providers/provider_taxonomies_list.yaml b/swagger-spec/preprint_providers/provider_taxonomies_list.yaml index 1ded87d..113c99b 100644 --- a/swagger-spec/preprint_providers/provider_taxonomies_list.yaml +++ b/swagger-spec/preprint_providers/provider_taxonomies_list.yaml @@ -1,12 +1,14 @@ -# /preprint_providers/{provider_id}/taxonomies/ +# /providers/preprints/{provider_id}/taxonomies/ get: - summary: List Taxonomies for a Preprint Provider + summary: List Taxonomies for a Preprint Provider (Deprecated) 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. + **Deprecated:** Use `subjects` endpoints instead. + #### Permissions - No authentication required for public providers. - Only authorized users can access restricted providers. @@ -15,6 +17,8 @@ get: - A JSON object with a `data` key containing an array of taxonomy resources. - Each taxonomy represents a subject that can be assigned to preprints. + deprecated: true + tags: - Preprint Providers - Taxonomies @@ -73,7 +77,7 @@ get: links: self: "https://api.test.osf.io/v2/taxonomies/biology/" links: - self: "https://api.test.osf.io/v2/preprint_providers/{provider_id}/taxonomies/" + self: "https://api.test.osf.io/v2/providers/preprints/{provider_id}/taxonomies/" next: null prev: null meta: diff --git a/swagger-spec/preprint_providers/subjects_highlighted_list.yaml b/swagger-spec/preprint_providers/subjects_highlighted_list.yaml index e69de29..2537e41 100644 --- a/swagger-spec/preprint_providers/subjects_highlighted_list.yaml +++ b/swagger-spec/preprint_providers/subjects_highlighted_list.yaml @@ -0,0 +1,84 @@ +# /provider/preprints/{provider_id}/subjects/highlighted/ +get: + summary: Preprints Providers Highlighted Subject List + description: >- + + This returns a list of highlighted subjects for a Preprints Provider. + + #### Permissions + + This information is public. + + #### Returns + + Returns a JSON object containing `data` and `links` keys. + + The `data` key contains an array of subject 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 preprint' + tags: + - Preprint Providers + operationId: preprint_provider_detail + x-response-schema: Preprint Provider + consumes: + - application/json + responses: + '200': + description: 'OK' + examples: + application/json: + data: + - id: 5c252d520989e100220edc4f + type: subjects + attributes: + text: Architecture + taxonomy_name: bepress + relationships: + parent: + data: + children: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d520989e100220edc4f/children/ + meta: { } + embeds: + parent: + errors: + - detail: Not found. + links: + self: https://api.staging.osf.io/v2/subjects/5c252d520989e100220edc4f/ + - id: 5c252d510989e100220edba7 + type: subjects + attributes: + text: Arts and Humanities + taxonomy_name: bepress + relationships: + parent: + data: + children: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edba7/children/ + meta: { } + embeds: + parent: + errors: + - detail: Not found. + links: + self: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edba7/ + meta: + total: 10 + per_page: 2 + version: '2.20' + links: + self: https://api.staging.osf.io/v2/providers/preprints/temp/subjects/highlighted/?page%5Bsize%5D=2 + first: + last: https://api.staging.osf.io/v2/providers/preprints/temp/subjects/highlighted/?page=5&page%5Bsize%5D=2 + prev: + next: https://api.staging.osf.io/v2/providers/preprints/temp/subjects/highlighted/?page=2&page%5Bsize%5D=2 diff --git a/swagger-spec/preprint_providers/subjects_list.yaml b/swagger-spec/preprint_providers/subjects_list.yaml index 77c3c79..96cdedb 100644 --- a/swagger-spec/preprint_providers/subjects_list.yaml +++ b/swagger-spec/preprint_providers/subjects_list.yaml @@ -1,63 +1,180 @@ +# /provider/preprints/{provider_id}/subjects/ get: - summary: List all taxonomies + summary: Preprints Providers Subject List description: >- - A paginated list of the taxonomies for a preprint provider. - The returned preprint providers taxonomies are sorted by their creation date, with the most recent - preprints appearing first. - - #### Returns - - Returns a JSON object containing `data` and `links` keys. + This returns a list of acceptable subjects for a Preprints Provider. + #### Permissions - The `data` key contains an array of 10 preprint providers. - Each resource in the array is a separate preprint provider object. + This information is public. + #### Returns - The `links` key contains a dictionary of links that can be used - for [pagination](#tag/Pagination). - + Returns a JSON object containing `data` and `links` keys. - 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. + The `data` key contains an array of subject 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: 'The unique identifier of the preprint provider.' + description: 'A short id for that preprint' tags: - Preprint Providers - operationId: preprint_provider_taxonomies_list - x-response-schema: 'Taxonomies' + operationId: preprint_provider_detail + x-response-schema: Preprint Provider + consumes: + - application/json responses: '200': description: 'OK' - schema: - $ref: '../taxonomies/definition.yaml' examples: application/json: data: - - links: - self: https://api.osf.io/v2/taxonomies/584240d854be81056ceca838/ - parents: - - https://api.osf.io/v2/taxonomies/584240d954be81056ceca97a/ + - id: 5c3e311a0989e101eede6afa + type: subjects + attributes: + text: Puppy Studies + taxonomy_name: bepress + relationships: + parent: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc16/ + meta: { } + data: + id: 5c252d510989e100220edc16 + type: subjects + children: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c3e311a0989e101eede6afa/children/ + meta: { } + embeds: + parent: + data: + id: 5c252d510989e100220edc16 + type: subjects + attributes: + text: Public Affairs, Public Policy and Public Administration + taxonomy_name: bepress + relationships: + parent: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc1e/ + meta: { } + data: + id: 5c252d510989e100220edc1e + type: subjects + children: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc16/children/ + meta: { } + embeds: + parent: + data: + id: 5c252d510989e100220edc1e + type: subjects + attributes: + text: Social and Behavioral Sciences + taxonomy_name: bepress + relationships: + parent: + data: + children: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc1e/children/ + meta: { } + embeds: + parent: + errors: + - detail: Not found. + links: + self: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc1e/ + links: + self: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc16/ + links: + self: https://api.staging.osf.io/v2/subjects/5c3e311a0989e101eede6afa/ + - id: 5c3e311a0989e101eede6af9 + type: subjects attributes: - text: History of Philosophy - parents: - - text: Philosophy - id: 584240d954be81056ceca97a - child_count: 0 - type: taxonomies - id: 584240d854be81056ceca838 + text: Transpersonal Psychology + taxonomy_name: bepress + relationships: + parent: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edbad/ + meta: { } + data: + id: 5c252d510989e100220edbad + type: subjects + children: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c3e311a0989e101eede6af9/children/ + meta: { } + embeds: + parent: + data: + id: 5c252d510989e100220edbad + type: subjects + attributes: + text: Psychology + taxonomy_name: bepress + relationships: + parent: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc1e/ + meta: { } + data: + id: 5c252d510989e100220edc1e + type: subjects + children: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edbad/children/ + meta: { } + embeds: + parent: + data: + id: 5c252d510989e100220edc1e + type: subjects + attributes: + text: Social and Behavioral Sciences + taxonomy_name: bepress + relationships: + parent: + data: + children: + links: + related: + href: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc1e/children/ + meta: { } + embeds: + parent: + errors: + - detail: Not found. + links: + self: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edc1e/ + links: + self: https://api.staging.osf.io/v2/subjects/5c252d510989e100220edbad/ + links: + self: https://api.staging.osf.io/v2/subjects/5c3e311a0989e101eede6af9/ + meta: + total: 1239 + per_page: 2 + version: '2.20' links: + self: https://api.staging.osf.io/v2/providers/preprints/temp/subjects/?page%5Bsize%5D=2 first: - last: https://api.osf.io/v2/preprint_providers/osf/taxonomies/?page=122 + last: https://api.staging.osf.io/v2/providers/preprints/temp/subjects/?page=620&page%5Bsize%5D=2 prev: - next: https://api.osf.io/v2/preprint_providers/osf/taxonomies/?page=2 - meta: - total: 1217 - per_page: 10 + next: https://api.staging.osf.io/v2/providers/preprints/temp/subjects/?page=2&page%5Bsize%5D=2 diff --git a/swagger-spec/preprints/list.yaml b/swagger-spec/preprints/list.yaml index b639c37..48c2413 100644 --- a/swagger-spec/preprints/list.yaml +++ b/swagger-spec/preprints/list.yaml @@ -81,7 +81,7 @@ get: provider: links: related: - href: 'https://api.osf.io/v2/preprint_providers/socarxiv/' + href: 'https://api.osf.io/v2/providers/preprints/socarxiv/' meta: {} links: self: 'https://api.osf.io/v2/preprints/hqb2p/' diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index bdee515..01c483f 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -1109,6 +1109,7 @@ tags: - 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. + - Retrieve citation styles associated with a specific preprint provider - name: Tokens description: >- **Personal Access Tokens** allow users to authenticate API requests without credentials. @@ -1546,36 +1547,42 @@ paths: # PREPRINT PROVIDERS # ########################## - /preprint_providers/: + /providers/preprints/: $ref: 'preprint_providers/list.yaml' - /preprint_providers/{provider_id}/: + /providers/preprints/{provider_id}/: $ref: 'preprint_providers/detail.yaml' - /preprint_providers/{provider_id}/preprints/: + /providers/preprints/{provider_id}/preprints/: $ref: 'preprint_providers/preprints_list.yaml' - /preprint_providers/{provider_id}/taxonomies/: + /providers/preprints/{provider_id}/taxonomies/: $ref: 'preprint_providers/provider_taxonomies_list.yaml' - /preprint_providers/{provider_id}/taxonomies/highlighted/: + /providers/preprints/{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/: + /providers/preprints/{provider_id}/licenses/: $ref: 'preprint_providers/licenses_list.yaml' - /preprint_providers/{provider_id}/moderators/: + /providers/preprints/{provider_id}/moderators/: $ref: 'preprint_providers/provider_moderator_list.yaml' - /preprint_providers/{provider_id}/moderators/{moderator_id}/: + /providers/preprints/{provider_id}/moderators/{moderator_id}/: $ref: 'preprint_providers/provider_moderator_detail.yaml' /providers/preprints/{provider_id}/withdraw_requests/: $ref: 'preprint_providers/withdraw_requests.yaml' + /providers/preprints/{provider_id}/subjects/: + $ref: 'preprint_providers/subjects_list.yaml' + + /providers/preprints/{provider_id}/subjects/highlighted/: + $ref: 'preprint_providers/subjects_highlighted_list.yaml' + ##################### # REGISTRATIONS # ##################### diff --git a/swagger-spec/users/preprints_list.yaml b/swagger-spec/users/preprints_list.yaml index db465fd..94f9f59 100644 --- a/swagger-spec/users/preprints_list.yaml +++ b/swagger-spec/users/preprints_list.yaml @@ -64,7 +64,7 @@ get: provider: links: related: - href: https://api.osf.io/v2/preprint_providers/osf/ + href: https://api.osf.io/v2/providers/preprints/osf/ meta: {} links: self: https://api.osf.io/v2/preprints/khbvy/ From 57355fac74e11cea651454d6be052367bcd9123b Mon Sep 17 00:00:00 2001 From: Ihor Sokhan Date: Fri, 6 Mar 2026 19:36:32 +0200 Subject: [PATCH 2/5] updated endpoints for registrations providers --- .../registration_providers/definition.yaml | 14 +++---- .../registration_providers/detail.yaml | 14 +++---- swagger-spec/registration_providers/list.yaml | 18 ++++----- swagger-spec/swagger.yaml | 37 +++---------------- 4 files changed, 29 insertions(+), 54 deletions(-) diff --git a/swagger-spec/registration_providers/definition.yaml b/swagger-spec/registration_providers/definition.yaml index 708e6b0..f9f2e6a 100644 --- a/swagger-spec/registration_providers/definition.yaml +++ b/swagger-spec/registration_providers/definition.yaml @@ -43,12 +43,12 @@ properties: banner_path: type: string description: The path to the banner image displayed for the provider. - example: /static/img/registration_providers/cos-logo.png + example: /static/img/providers/registrations/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 + example: /static/img/providers/registrations/cos-logo.png header_text: type: string @@ -121,7 +121,7 @@ properties: href: type: string format: uri - example: https://api.osf.io/v2/registration_providers/osf/licenses/ + example: https://api.osf.io/v2/providers/registrations/osf/licenses/ meta: type: object @@ -138,7 +138,7 @@ properties: href: type: string format: uri - example: https://api.osf.io/v2/registration_providers/osf/taxonomies/ + example: https://api.osf.io/v2/providers/registrations/osf/taxonomies/ meta: type: object @@ -155,7 +155,7 @@ properties: href: type: string format: uri - example: https://api.osf.io/v2/registration_providers/osf/registrations/ + example: https://api.osf.io/v2/providers/registrations/osf/registrations/ meta: type: object @@ -167,13 +167,13 @@ properties: type: string format: uri description: The canonical API endpoint for this provider. - example: https://api.osf.io/v2/registration_providers/osf/ + example: https://api.osf.io/v2/providers/registrations/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/ + example: https://api.osf.io/v2/providers/registrations/osf/registrations/ external_url: type: string diff --git a/swagger-spec/registration_providers/detail.yaml b/swagger-spec/registration_providers/detail.yaml index 0febf1a..4633270 100644 --- a/swagger-spec/registration_providers/detail.yaml +++ b/swagger-spec/registration_providers/detail.yaml @@ -84,28 +84,28 @@ get: licenses_acceptable: links: related: - href: https://api.osf.io/v2/registration_providers/osf/licenses/ + href: https://api.osf.io/v2/providers/registrations/osf/licenses/ meta: {} taxonomies: links: related: - href: https://api.osf.io/v2/registration_providers/osf/taxonomies/ + href: https://api.osf.io/v2/providers/registrations/osf/taxonomies/ meta: {} registrations: links: related: - href: https://api.osf.io/v2/registration_providers/osf/registrations/ + href: https://api.osf.io/v2/providers/registrations/osf/registrations/ meta: {} links: - self: https://api.osf.io/v2/registration_providers/osf/ - registrations: https://api.osf.io/v2/registration_providers/osf/registrations/ + self: https://api.osf.io/v2/providers/registrations/osf/ + registrations: https://api.osf.io/v2/providers/registrations/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" + banner_path: "/static/img/providers/registrations/cos-logo.png" + logo_path: "/static/img/providers/registrations/cos-logo.png" subjects_acceptable: [] description: A scholarly commons to connect the entire research cycle social_facebook: '' diff --git a/swagger-spec/registration_providers/list.yaml b/swagger-spec/registration_providers/list.yaml index ffcf91c..b3b5dfd 100644 --- a/swagger-spec/registration_providers/list.yaml +++ b/swagger-spec/registration_providers/list.yaml @@ -1,4 +1,4 @@ -# /registration_providers/ +# /providers/registrations/ get: summary: List all Registration Providers description: >- @@ -26,7 +26,7 @@ get: 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. + https://api.osf.io/v2/providers/registrations/?filter[id]=osf. Preprint Providers may be filtered by their `id`, `name`, and `description` @@ -47,28 +47,28 @@ get: licenses_acceptable: links: related: - href: https://api.osf.io/v2/registration_providers/osf/licenses/ + href: https://api.osf.io/v2/providers/registrations/osf/licenses/ meta: {} taxonomies: links: related: - href: https://api.osf.io/v2/registration_providers/osf/taxonomies/ + href: https://api.osf.io/v2/providers/registrations/osf/taxonomies/ meta: {} registrations: links: related: - href: https://api.osf.io/v2/registration_providers/osf/registrations/ + href: https://api.osf.io/v2/providers/registrations/osf/registrations/ meta: {} links: - self: https://api.osf.io/v2/registration_providers/osf/ - registrations: https://api.osf.io/v2/registration_providers/osf/registrations/ + self: https://api.osf.io/v2/providers/registrations/osf/ + registrations: https://api.osf.io/v2/providers/registrations/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" + banner_path: "/static/img/providers/registrations/cos-logo.png" + logo_path: "/static/img/providers/registrations/cos-logo.png" subjects_acceptable: [] description: A scholarly commons to connect the entire research cycle social_facebook: '' diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 01c483f..6243eef 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -1941,6 +1941,9 @@ paths: /providers/collections/{provider_id}/submissions/: $ref: 'collection_providers/submissions_list.yaml' + /provider/collections/{provider_id}/subjects/: + $ref: 'collection_providers/subjects.yaml' + /providers/collections/{provider_id}/subjects/highlighted/: $ref: 'collection_providers/subjects_highlighted_list.yaml' @@ -1967,37 +1970,9 @@ paths: /collection_submission_actions/: $ref: 'collection_submission_actions/list.yaml' - ############################ - # COLLECTIONS PROVIDER # - ############################ - - /provider/collections/: - $ref: 'collection_providers/list.yaml' - - /provider/collections/{provider_id}/: - $ref: 'collection_providers/detail.yaml' - - /provider/collections/{provider_id}/licenses/: - $ref: 'collection_providers/licenses_list.yaml' - - /provider/collections/{provider_id}/submissions/: - $ref: 'collection_providers/submissions_list.yaml' - - /provider/collections/{provider_id}/subjects/: - $ref: 'collection_providers/subjects.yaml' - - /provider/collections/{provider_id}/subjects/highlighted/: - $ref: 'collection_providers/subjects_highlighted_list.yaml' - - /provider/collections/{provider_id}/moderators/: - $ref: 'collection_providers/moderators_list.yaml' - - /provider/collections/{provider_id}/moderators/{moderator_id}/: - $ref: 'collection_providers/moderators_detail.yaml' - -####################################### -# REQUESTS # -####################################### + ####################################### + # REQUESTS # + ####################################### /requests/{request_id}/: $ref: 'requests/detail.yaml' From a89d8bf4506b018d21a603be9fa63cf55b58c489 Mon Sep 17 00:00:00 2001 From: Ihor Sokhan Date: Fri, 6 Mar 2026 19:50:03 +0200 Subject: [PATCH 3/5] removed unused yaml files --- .../provider_moderator_detail.yaml | 45 ----- .../provider_moderator_list.yaml | 43 ---- .../taxonomies_highlighted_list.yaml | 100 ---------- .../collection_providers/taxonomies_list.yaml | 87 --------- .../preprint_providers/moderators_detail.yaml | 62 ------ .../preprint_providers/moderators_list.yaml | 183 ------------------ 6 files changed, 520 deletions(-) delete mode 100644 swagger-spec/collection_providers/provider_moderator_detail.yaml delete mode 100644 swagger-spec/collection_providers/provider_moderator_list.yaml delete mode 100644 swagger-spec/collection_providers/taxonomies_highlighted_list.yaml delete mode 100644 swagger-spec/collection_providers/taxonomies_list.yaml delete mode 100644 swagger-spec/preprint_providers/moderators_detail.yaml delete mode 100644 swagger-spec/preprint_providers/moderators_list.yaml diff --git a/swagger-spec/collection_providers/provider_moderator_detail.yaml b/swagger-spec/collection_providers/provider_moderator_detail.yaml deleted file mode 100644 index 9deda90..0000000 --- a/swagger-spec/collection_providers/provider_moderator_detail.yaml +++ /dev/null @@ -1,45 +0,0 @@ -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. - - diff --git a/swagger-spec/collection_providers/provider_moderator_list.yaml b/swagger-spec/collection_providers/provider_moderator_list.yaml deleted file mode 100644 index 6395d7d..0000000 --- a/swagger-spec/collection_providers/provider_moderator_list.yaml +++ /dev/null @@ -1,43 +0,0 @@ - -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. diff --git a/swagger-spec/collection_providers/taxonomies_highlighted_list.yaml b/swagger-spec/collection_providers/taxonomies_highlighted_list.yaml deleted file mode 100644 index 8388bb8..0000000 --- a/swagger-spec/collection_providers/taxonomies_highlighted_list.yaml +++ /dev/null @@ -1,100 +0,0 @@ -# /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 deleted file mode 100644 index b91818d..0000000 --- a/swagger-spec/collection_providers/taxonomies_list.yaml +++ /dev/null @@ -1,87 +0,0 @@ -# /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/moderators_detail.yaml b/swagger-spec/preprint_providers/moderators_detail.yaml deleted file mode 100644 index a419908..0000000 --- a/swagger-spec/preprint_providers/moderators_detail.yaml +++ /dev/null @@ -1,62 +0,0 @@ -# /providers/preprints/{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: 'moderator_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/providers/preprints/{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 deleted file mode 100644 index a598899..0000000 --- a/swagger-spec/preprint_providers/moderators_list.yaml +++ /dev/null @@ -1,183 +0,0 @@ -# /providers/preprints/{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: 'moderator_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/providers/preprints/{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/providers/preprints/{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/providers/preprints/{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. From 5acb7e773f7875bac0e48b6f093308e590c827a6 Mon Sep 17 00:00:00 2001 From: Ihor Sokhan Date: Fri, 6 Mar 2026 19:58:33 +0200 Subject: [PATCH 4/5] marked taxonomies endpoint as deprecated --- .../provider_taxonomies_highlighted_list.yaml | 3 ++- .../registration_providers/provider_taxonomies_list.yaml | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/swagger-spec/registration_providers/provider_taxonomies_highlighted_list.yaml b/swagger-spec/registration_providers/provider_taxonomies_highlighted_list.yaml index 8d88ef5..93ff20a 100644 --- a/swagger-spec/registration_providers/provider_taxonomies_highlighted_list.yaml +++ b/swagger-spec/registration_providers/provider_taxonomies_highlighted_list.yaml @@ -1,5 +1,6 @@ get: - summary: List Highlighted Taxonomies + summary: List Highlighted Taxonomies (Deprecated) + deprecated: true description: | Retrieves highlighted taxonomies associated with the provider. tags: diff --git a/swagger-spec/registration_providers/provider_taxonomies_list.yaml b/swagger-spec/registration_providers/provider_taxonomies_list.yaml index fa4789c..7d86794 100644 --- a/swagger-spec/registration_providers/provider_taxonomies_list.yaml +++ b/swagger-spec/registration_providers/provider_taxonomies_list.yaml @@ -1,5 +1,6 @@ get: - summary: List Provider Taxonomies + summary: List Provider Taxonomies (Deprecated) + deprecated: true description: | Retrieves a list of all taxonomies associated with the provider. tags: From 85dbcdd2a27ad7f27e57a7439ceebd9cda1d7c03 Mon Sep 17 00:00:00 2001 From: Ihor Sokhan Date: Fri, 6 Mar 2026 20:16:44 +0200 Subject: [PATCH 5/5] added missing post/patch/delete docs for moderators in collections providers --- .../moderator_definition.yaml | 98 +++++ .../moderators_detail.yaml | 278 +++++++++---- .../collection_providers/moderators_list.yaml | 381 ++++++++++-------- 3 files changed, 499 insertions(+), 258 deletions(-) create mode 100644 swagger-spec/collection_providers/moderator_definition.yaml diff --git a/swagger-spec/collection_providers/moderator_definition.yaml b/swagger-spec/collection_providers/moderator_definition.yaml new file mode 100644 index 0000000..ae7df01 --- /dev/null +++ b/swagger-spec/collection_providers/moderator_definition.yaml @@ -0,0 +1,98 @@ +type: object +description: A moderator for a collection 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 collection 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: + collection_provider: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + enum: + - collection_providers + description: Must be 'collection_providers'. + example: collection_providers + id: + type: string + description: The unique identifier of the collection 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/providers/collections/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: + collection_provider: + data: + type: collection_providers + id: provider_1 + links: + self: https://api.test.osf.io/v2/providers/collections/provider_1/moderators/moderator_1/ diff --git a/swagger-spec/collection_providers/moderators_detail.yaml b/swagger-spec/collection_providers/moderators_detail.yaml index 47aaee2..1b84ffa 100644 --- a/swagger-spec/collection_providers/moderators_detail.yaml +++ b/swagger-spec/collection_providers/moderators_detail.yaml @@ -1,116 +1,216 @@ -# /provider/collections/{provider_id}/moderators/{moderator_id}/: +# /providers/collections/{provider_id}/moderators/{moderator_id}/ + get: - summary: Collections Providers Moderators Detail + summary: Retrieve a Moderator for a Collection Provider description: >- - - This returns details for a moderator of a Collections Provider. + Retrieve the details of a specific moderator for a collection provider, including their permission group and user information. #### Permissions - - This information is only available to Collection Provider moderators or admins. + - The authenticated user must be an administrator of the collection 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: + - Collection Providers - Returns a JSON object containing `data` and `links` keys. + operationId: collection_provider_moderator_detail - Returns a JSON object with a `data` key containing the representation of the requested collection provider moderator object, if the request is successful. parameters: - in: path + name: provider_id type: string required: true - name: provider_id - description: 'A short id for that collection' + description: The unique identifier of the collection provider. + - in: path + name: moderator_id type: string required: true - name: moderator_id - description: 'A short id for that moderator' + description: The unique identifier of the moderator. + + responses: + '200': + description: Successful retrieval of the moderator. + schema: + $ref: 'moderator_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: + collection_provider: + data: + type: "collection_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/providers/collections/{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 Collection Provider + description: >- + Update the permission group for a specific moderator on a collection provider. + + ## Permissions + - The authenticated user must be an administrator of the collection 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 collection 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: - Collection Providers - operationId: collection_provider_detail - x-response-schema: Collection Provider - consumes: - - application/json + + operationId: collection_provider_moderator_update + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the collection 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 collection submissions. + - `admin`: Can manage submissions and other moderators. + + example: + data: + type: moderators + id: "{moderator_id}" + attributes: + permission_group: "admin" + responses: '200': - description: 'OK' + description: Moderator successfully updated. + schema: + $ref: 'moderator_definition.yaml' examples: application/json: data: - id: m8ku3 - type: moderators + id: "moderator_1" + type: "moderators" attributes: - full_name: DC Test - AMC - permission_group: admin + full_name: "Ada Lovelace" + email: "ada.lovelace@example.com" + permission_group: "admin" + date_added: "2024-01-15T12:34:56Z" relationships: - user: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/ - meta: { } - data: - id: m8ku3 - type: users - provider: - links: - related: - href: https://api.staging.osf.io/v2/providers/collections/colmod/ - meta: { } - data: - id: colmod - type: collection-providers - embeds: - user: + collection_provider: data: - id: m8ku3 - type: users - attributes: - full_name: DC Test - AMC - given_name: DC - middle_names: Test - - family_name: AMC - suffix: '' - date_registered: '2022-09-14T11:28:08.681787Z' - active: true - timezone: Etc/UTC - locale: en_US - social: { } - employment: [ ] - education: [ ] - relationships: - nodes: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/nodes/ - meta: { } - groups: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/groups/ - meta: { } - registrations: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/registrations/ - meta: { } - institutions: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/institutions/ - meta: { } - self: - href: https://api.staging.osf.io/v2/users/m8ku3/relationships/institutions/ - meta: { } - preprints: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/preprints/ - meta: { } - links: - html: https://staging.osf.io/m8ku3/ - profile_image: https://secure.gravatar.com/avatar/ce38ca4e4a1361446468960716f57b5e?d=identicon - self: https://api.staging.osf.io/v2/users/m8ku3/ + type: "collection_providers" + id: "{provider_id}" links: - self: https://api.staging.osf.io/v2/providers/collections/colmod/moderators/m8ku3/ + self: "https://api.test.osf.io/v2/providers/collections/{provider_id}/moderators/moderator_1/" meta: - version: '2.20' + 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 Collection Provider + description: >- + Remove a moderator from a collection provider. + + ## Permissions + - The authenticated user must be an administrator of the collection provider. + + ## Returns + - Returns a `204 No Content` response if the deletion is successful. + - If unsuccessful, returns an `errors` object detailing the issue. + + tags: + - Collection Providers + + operationId: collection_provider_moderator_delete + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the collection 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/collection_providers/moderators_list.yaml b/swagger-spec/collection_providers/moderators_list.yaml index ed28121..5852127 100644 --- a/swagger-spec/collection_providers/moderators_list.yaml +++ b/swagger-spec/collection_providers/moderators_list.yaml @@ -1,196 +1,239 @@ -# /provider/collections/{provider_id}/moderators/: +# /providers/collections/{provider_id}/moderators/ + get: - summary: Collections Providers Moderators List + summary: List Moderators for a Collection Provider description: >- + Retrieve a list of all moderators assigned to a specific collection provider. - This returns a list of moderators for a Collections Provider. - - #### Permissions + ## Permissions + - The authenticated user must be an administrator of the collection provider. - This information is only available to Collection Provider moderators or admins. - - #### Returns + ## 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 containing `data` and `links` keys. + tags: + - Collection Providers - The `data` key contains an array of moderator ids. + operationId: collection_provider_moderator_list - The `links` key contains a dictionary of links that can be used for [pagination](#tag/Pagination). parameters: - in: path + name: provider_id type: string required: true - name: provider_id - description: 'A short id for that collection' - tags: - - Collection Providers - operationId: collection_provider_detail - x-response-schema: Collection Provider - consumes: - - application/json + description: The unique identifier of the collection 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: 'OK' + 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: nmwt5 + - 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: + collection_provider: + data: + type: "collection_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/providers/collections/{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: + collection_provider: + data: + type: "collection_providers" + id: "{provider_id}" + links: + self: "https://api.test.osf.io/v2/providers/collections/{provider_id}/moderators/moderator_2/" + links: + self: "https://api.test.osf.io/v2/providers/collections/{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 collection provider matches the given ID. + +post: + summary: Add a Moderator to a Collection Provider + description: >- + Add a new moderator to the specified collection provider. + + ## Permissions + - The authenticated user must be an administrator of the collection 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: + - Collection Providers + + operationId: collection_provider_moderator_create + + parameters: + - in: path + name: provider_id + type: string + required: true + description: The unique identifier of the collection 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 collection 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: - full_name: Blaine Butler - permission_group: admin + permission_group: moderator relationships: user: - links: - related: - href: https://api.staging.osf.io/v2/users/nmwt5/ - meta: {} data: - id: nmwt5 type: users - provider: - links: - related: - href: https://api.staging.osf.io/v2/providers/collections/colmod/ - meta: {} - data: - id: colmod - type: collection-providers - embeds: - user: - data: - id: nmwt5 - type: users - attributes: - full_name: Blaine Butler - given_name: Blaine - middle_names: '' - family_name: Butler - suffix: '' - date_registered: '2022-11-03T19:23:28.110924Z' - active: false - timezone: Etc/UTC - locale: en_US - social: {} - employment: [] - education: [] - relationships: - nodes: - links: - related: - href: https://api.staging.osf.io/v2/users/nmwt5/nodes/ - meta: {} - groups: - links: - related: - href: https://api.staging.osf.io/v2/users/nmwt5/groups/ - meta: {} - registrations: - links: - related: - href: https://api.staging.osf.io/v2/users/nmwt5/registrations/ - meta: {} - institutions: - links: - related: - href: https://api.staging.osf.io/v2/users/nmwt5/institutions/ - meta: {} - self: - href: https://api.staging.osf.io/v2/users/nmwt5/relationships/institutions/ - meta: {} - preprints: - links: - related: - href: https://api.staging.osf.io/v2/users/nmwt5/preprints/ - meta: {} - links: - html: https://staging.osf.io/nmwt5/ - profile_image: https://secure.gravatar.com/avatar/4a1f62c6580a151e5c1c0aec72b7fc2a?d=identicon - self: https://api.staging.osf.io/v2/users/nmwt5/ - links: - self: https://api.staging.osf.io/v2/providers/collections/colmod/moderators/nmwt5/ - - id: m8ku3 - type: moderators + 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: DC Test - AMC - permission_group: admin + full_name: "Grace Hopper" + email: "grace.hopper@example.com" + permission_group: "moderator" + date_added: "2024-02-01T14:20:00Z" relationships: - user: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/ - meta: {} + collection_provider: data: - id: m8ku3 - type: users - provider: - links: - related: - href: https://api.staging.osf.io/v2/providers/collections/colmod/ - meta: {} - data: - id: colmod - type: collection-providers - embeds: - user: - data: - id: m8ku3 - type: users - attributes: - full_name: DC Test - AMC - given_name: DC - middle_names: Test - - family_name: AMC - suffix: '' - date_registered: '2022-09-14T11:28:08.681787Z' - active: true - timezone: Etc/UTC - locale: en_US - social: {} - employment: [] - education: [] - relationships: - nodes: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/nodes/ - meta: {} - groups: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/groups/ - meta: {} - registrations: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/registrations/ - meta: {} - institutions: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/institutions/ - meta: {} - self: - href: https://api.staging.osf.io/v2/users/m8ku3/relationships/institutions/ - meta: {} - preprints: - links: - related: - href: https://api.staging.osf.io/v2/users/m8ku3/preprints/ - meta: {} - links: - html: https://staging.osf.io/m8ku3/ - profile_image: https://secure.gravatar.com/avatar/ce38ca4e4a1361446468960716f57b5e?d=identicon - self: https://api.staging.osf.io/v2/users/m8ku3/ + type: "collection_providers" + id: "{provider_id}" links: - self: https://api.staging.osf.io/v2/providers/collections/colmod/moderators/m8ku3/ + self: "https://api.test.osf.io/v2/providers/collections/{provider_id}/moderators/moderator_3/" meta: - total: 8 - per_page: 2 - version: '2.20' - links: - self: https://api.staging.osf.io/v2/providers/collections/colmod/moderators/?page%5Bsize%5D=2 - first: - last: https://api.staging.osf.io/v2/providers/collections/colmod/moderators/?page=4&page%5Bsize%5D=2 - prev: - next: https://api.staging.osf.io/v2/providers/collections/colmod/moderators/?page=2&page%5Bsize%5D=2 \ No newline at end of file + 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 collection provider matches the given ID. +