From c73acf6be4c273e0b562083c07ea95d67483e113 Mon Sep 17 00:00:00 2001 From: Erin Braswell Date: Thu, 11 May 2017 16:21:16 -0400 Subject: [PATCH 1/9] Add actions for adding and removing view only links [OSF-7309] (#60) * Add actions for adding and removing view only links * Also add anonymous_link param to serializer docs --- swagger-spec/logs/actions.yaml | 4 ++++ swagger-spec/logs/definition.yaml | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/swagger-spec/logs/actions.yaml b/swagger-spec/logs/actions.yaml index b415b577944..9a09617bb53 100644 --- a/swagger-spec/logs/actions.yaml +++ b/swagger-spec/logs/actions.yaml @@ -44,6 +44,10 @@ get: * `external_ids_added`: An external identifier is added to a Node (e.g. DOI, ARK) + * `view_only_link_added`: A view-only link was added to a Node + + * `view_only_link_removed`: A view-only link was removed from a Node + --- * `contributor_added`: A Contributor is added to a Node diff --git a/swagger-spec/logs/definition.yaml b/swagger-spec/logs/definition.yaml index 02f67b8e1fa..ea96c52c44a 100644 --- a/swagger-spec/logs/definition.yaml +++ b/swagger-spec/logs/definition.yaml @@ -43,6 +43,10 @@ properties: type: string readOnly: true description: 'The addon associated with the connected node.' + anonymous_link: + type: boolean + readOnly: true + description: 'The link added to the node was anonymous.' bucket: type: string readOnly: true From 5d274dc6d7e819f86cb7bea720e639f3a477d948 Mon Sep 17 00:00:00 2001 From: Erin Braswell Date: Thu, 1 Jun 2017 16:49:05 -0400 Subject: [PATCH 2/9] Add docs for new preprint identifier relationship and link [OSF-7772] (#61) * Add examples to list and detail for preprints * Add identifiers relationship to definition [#OSF-7772] Also add links description and docs for new preprint_doi field --- swagger-spec/preprints/definition.yaml | 9 +++++++++ swagger-spec/preprints/detail.yaml | 6 ++++++ swagger-spec/preprints/list.yaml | 6 ++++++ 3 files changed, 21 insertions(+) diff --git a/swagger-spec/preprints/definition.yaml b/swagger-spec/preprints/definition.yaml index e10787f7a88..30583366c69 100644 --- a/swagger-spec/preprints/definition.yaml +++ b/swagger-spec/preprints/definition.yaml @@ -65,6 +65,10 @@ properties: type: string readOnly: true description: 'A relationship to the citation of the preprint.' + identifiers: + type: string + readOnly: true + description: 'A relationship to the identifiers associated with the preprint.' license: type: string readOnly: false @@ -97,6 +101,11 @@ properties: format: URL readOnly: true description: 'A link to the project on the OSF that was created for the preprint, or from which the preprint was created.' + preprint_doi: + type: string + format: URL + readOnly: true + description: 'The URL representation of the OSF assigned DOI for the preprint.' self: type: string format: URL diff --git a/swagger-spec/preprints/detail.yaml b/swagger-spec/preprints/detail.yaml index 461f6f18afe..584aea612e7 100644 --- a/swagger-spec/preprints/detail.yaml +++ b/swagger-spec/preprints/detail.yaml @@ -42,6 +42,11 @@ get: related: href: https://api.osf.io/v2/preprints/khbvy/citation/ meta: {} + identifiers: + links: + related: + href: https://api.osf.io/v2/preprints/khbvy/identifiers/ + meta: {} primary_file: links: related: @@ -56,6 +61,7 @@ get: self: https://api.osf.io/v2/preprints/khbvy/ html: https://osf.io/khbvy/ doi: https://dx.doi.org/10.1371/journal.pbio.1002456 + preprint_doi: https://dx.doi.org/10.5072/FK2OSF.IO/KHBVY attributes: doi: 10.1371/journal.pbio.1002456 license_record: diff --git a/swagger-spec/preprints/list.yaml b/swagger-spec/preprints/list.yaml index 0ca5d2fae6d..39be4bf7e2b 100644 --- a/swagger-spec/preprints/list.yaml +++ b/swagger-spec/preprints/list.yaml @@ -55,6 +55,11 @@ get: related: href: 'https://api.osf.io/v2/preprints/hqb2p/citation/' meta: {} + identifiers: + links: + related: + href: 'https://api.osf.io/v2/preprints/hqb2p/identifiers/' + meta: {} primary_file: links: related: @@ -73,6 +78,7 @@ get: links: self: 'https://api.osf.io/v2/preprints/hqb2p/' html: 'https://osf.io/preprints/socarxiv/hqb2p/' + preprint_doi: 'https://dx.doi.org/10.5072/FK2OSF.IO/HQB2P' attributes: doi: null license_record: From 2dc42ea024e7ed2f6bb46b380e6e260287b9335d Mon Sep 17 00:00:00 2001 From: Casey Rollins Date: Fri, 2 Jun 2017 09:18:28 -0400 Subject: [PATCH 3/9] Add 'Error Codes' to list of fake endpoints. (#62) --- src/main/javascript/view/OperationView.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/main/javascript/view/OperationView.js b/src/main/javascript/view/OperationView.js index b228af05ea1..e1e357aff57 100644 --- a/src/main/javascript/view/OperationView.js +++ b/src/main/javascript/view/OperationView.js @@ -16,7 +16,8 @@ SwaggerUi.Views.OperationView = Backbone.View.extend({ 'Introduction', 'General API Usage', 'Versioning', 'Filtering', 'Embedding', 'Pagination', 'Create/Update Requests', 'Attribute Validation', 'Entities', - 'Entity Collections', 'Errors', 'Enum Fields', 'Actions' + 'Entity Collections', 'Errors', 'Enum Fields', 'Actions', + 'Error Codes' ]; opts = opts || {}; From 2d31ddae738e5cc03d4e766bcd977564054c5fd8 Mon Sep 17 00:00:00 2001 From: Casey Rollins Date: Mon, 19 Jun 2017 15:03:08 -0400 Subject: [PATCH 4/9] Specify view only link for anonymous_link log action. (#63) --- swagger-spec/logs/definition.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/swagger-spec/logs/definition.yaml b/swagger-spec/logs/definition.yaml index ea96c52c44a..0671fe91176 100644 --- a/swagger-spec/logs/definition.yaml +++ b/swagger-spec/logs/definition.yaml @@ -46,7 +46,7 @@ properties: anonymous_link: type: boolean readOnly: true - description: 'The link added to the node was anonymous.' + description: 'The view only link added to the node was anonymous.' bucket: type: string readOnly: true From 042a37ac17dc02b47399a6220c5d7faea2f19f46 Mon Sep 17 00:00:00 2001 From: Casey Rollins Date: Tue, 20 Jun 2017 09:21:11 -0400 Subject: [PATCH 5/9] [feature] Document Authorization and Rate Limiting [OSF-8172][OSF-8068] (#64) * Add documentation for authentication. * Alphabetize intro sections. * Add throttle rates and note about Retry header. --- src/main/javascript/view/OperationView.js | 9 +++--- swagger-spec/introduction/authentication.yaml | 32 +++++++++++++++++++ ...uests.yaml => create_update_requests.yaml} | 0 ...{osf_enum_fields.yaml => enum_fields.yaml} | 0 swagger-spec/introduction/error_codes.yaml | 9 ++++++ .../introduction/general_api_usage.yaml | 2 +- swagger-spec/swagger.yaml | 29 +++++++++-------- 7 files changed, 62 insertions(+), 19 deletions(-) create mode 100644 swagger-spec/introduction/authentication.yaml rename swagger-spec/introduction/{put_patch_requests.yaml => create_update_requests.yaml} (100%) rename swagger-spec/introduction/{osf_enum_fields.yaml => enum_fields.yaml} (100%) diff --git a/src/main/javascript/view/OperationView.js b/src/main/javascript/view/OperationView.js index e1e357aff57..a5255465c93 100644 --- a/src/main/javascript/view/OperationView.js +++ b/src/main/javascript/view/OperationView.js @@ -13,11 +13,10 @@ SwaggerUi.Views.OperationView = Backbone.View.extend({ initialize: function (opts) { var api_topics = [ - 'Introduction', 'General API Usage', 'Versioning', - 'Filtering', 'Embedding', 'Pagination', - 'Create/Update Requests', 'Attribute Validation', 'Entities', - 'Entity Collections', 'Errors', 'Enum Fields', 'Actions', - 'Error Codes' + 'Introduction', 'General Usage', 'Actions', + 'Attribute Validation', 'Authentication', 'Create/Update Requests', + 'Embedding', 'Entities', 'Entity Collections', 'Enum Fields', + 'Errors', 'Error Codes', 'Filtering', 'Pagination', 'Versioning' ]; opts = opts || {}; diff --git a/swagger-spec/introduction/authentication.yaml b/swagger-spec/introduction/authentication.yaml new file mode 100644 index 00000000000..232bd611c79 --- /dev/null +++ b/swagger-spec/introduction/authentication.yaml @@ -0,0 +1,32 @@ +get: + summary: Authentication + description: >- + #### Token Auth + + 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 " + + 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. + + #### OAuth + + 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/tokens/) or our [testing server](https://test.osf.io/settings/tokens/)). + + + We will be adding narrative documentation for handling OAuth flows, but for now, if you're familiar with OAuth, you can check out the [CAS overlay documentation](https://github.com/CenterForOpenScience/cas-overlay#web-server-authorization) for options. + + We've also created a [test application](https://github.com/abought/osf_oauth2_demo) for verifying that our OAuth workflow works correctly. + If you set up an OAuth application on https://test.osf.io/, you should be able to add the client secret and client id to the settings file and it should work properly. + If it does not, please let us know. + + operationId: authentication + tags: + - Introduction + responses: + '200': + description: OK diff --git a/swagger-spec/introduction/put_patch_requests.yaml b/swagger-spec/introduction/create_update_requests.yaml similarity index 100% rename from swagger-spec/introduction/put_patch_requests.yaml rename to swagger-spec/introduction/create_update_requests.yaml diff --git a/swagger-spec/introduction/osf_enum_fields.yaml b/swagger-spec/introduction/enum_fields.yaml similarity index 100% rename from swagger-spec/introduction/osf_enum_fields.yaml rename to swagger-spec/introduction/enum_fields.yaml diff --git a/swagger-spec/introduction/error_codes.yaml b/swagger-spec/introduction/error_codes.yaml index f3266d1bfd8..4455b7cfbb2 100644 --- a/swagger-spec/introduction/error_codes.yaml +++ b/swagger-spec/introduction/error_codes.yaml @@ -76,6 +76,15 @@ get: The user has sent too many requests in a given amount of time. + Wait at least the amount of time specified in the `Retry-After` header of the response before sending another request. + + + [Authenticated](#Introduction_authentication) requests have a rate limit of 10,000/day. + + + Unauthenticated requests have a rate limit of 100/hour. + + `5xx` **Server Errors** diff --git a/swagger-spec/introduction/general_api_usage.yaml b/swagger-spec/introduction/general_api_usage.yaml index bc5e12b1052..a88fcb71462 100644 --- a/swagger-spec/introduction/general_api_usage.yaml +++ b/swagger-spec/introduction/general_api_usage.yaml @@ -1,5 +1,5 @@ get: - summary: General API Usage + summary: General Usage description: >- The OSF API generally conforms to the [JSON-API v1.0 spec](http://jsonapi.org/format/1.0/). Where exceptions exist, they will be noted. diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 32552bffa0b..a44241720b3 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -30,26 +30,26 @@ paths: /general_api_usage/: $ref: 'introduction/general_api_usage.yaml' - /entities/: - $ref: 'introduction/entities.yaml' - - /entity_collections/: - $ref: 'introduction/entity_collections.yaml' + /attribute_validation/: + $ref: 'introduction/attribute_validation.yaml' - /osf_enum_fields/: - $ref: 'introduction/osf_enum_fields.yaml' + /authentication/: + $ref: 'introduction/authentication.yaml' - /filtering/: - $ref: 'introduction/filtering.yaml' + /create_update_requests/: + $ref: 'introduction/create_update_requests.yaml' /embedding/: $ref: 'introduction/embedding.yaml' - /put_patch_requests/: - $ref: 'introduction/put_patch_requests.yaml' + /entities/: + $ref: 'introduction/entities.yaml' - /attribute_validation/: - $ref: 'introduction/attribute_validation.yaml' + /entity_collections/: + $ref: 'introduction/entity_collections.yaml' + + /enum_fields/: + $ref: 'introduction/enum_fields.yaml' /errors/: $ref: 'introduction/errors.yaml' @@ -57,6 +57,9 @@ paths: /error_codes/: $ref: 'introduction/error_codes.yaml' + /filtering/: + $ref: 'introduction/filtering.yaml' + /pagination/: $ref: 'introduction/pagination.yaml' From 2ce901ad84c328d88f9aafb397dec0c24cdf3a2e Mon Sep 17 00:00:00 2001 From: Casey Rollins Date: Tue, 20 Jun 2017 09:25:40 -0400 Subject: [PATCH 6/9] [feature] Add Version Documentation [OSF-7667][OSF-8069] (#65) * Add CHANGELOG * Document versioning changes throughout the docs. --- swagger-spec/institutions/nodes_list.yaml | 4 +++ swagger-spec/introduction/pagination.yaml | 5 +++ swagger-spec/introduction/versioning.yaml | 32 +++++++++++++++++++ swagger-spec/nodes/definition.yaml | 2 +- .../preprint_providers/definition.yaml | 10 +++--- swagger-spec/registrations/definition.yaml | 4 +++ swagger-spec/taxonomies/definition.yaml | 2 +- swagger-spec/users/list.yaml | 4 +++ 8 files changed, 56 insertions(+), 7 deletions(-) diff --git a/swagger-spec/institutions/nodes_list.yaml b/swagger-spec/institutions/nodes_list.yaml index fe28aef393e..33f50552e20 100644 --- a/swagger-spec/institutions/nodes_list.yaml +++ b/swagger-spec/institutions/nodes_list.yaml @@ -3,6 +3,10 @@ get: description: >- A paginated list of all nodes affiliated with an institution. + #### Versioning + + As of version `2.2`, affiliated components (in addition to affiliated top-level projects) are returned from this endpoint. + #### Returns Returns a JSON object containing `data` and `links` keys. diff --git a/swagger-spec/introduction/pagination.yaml b/swagger-spec/introduction/pagination.yaml index 0e3cb13664a..c7d414016ad 100644 --- a/swagger-spec/introduction/pagination.yaml +++ b/swagger-spec/introduction/pagination.yaml @@ -10,6 +10,11 @@ get: If there are only enough results to fill one page, the `first`, `last`, `prev`, and `next` links will be null. + #### Versioning + + As of version `2.3`, pagination links conform to the JSON API specification. + Meta information was pulled out of the `links` object and placed in a top-level `meta` object. + The `meta` key contains the total number of entities available, as well as the current number of results displayed per page. diff --git a/swagger-spec/introduction/versioning.yaml b/swagger-spec/introduction/versioning.yaml index 16229945b73..76ea64c5eda 100644 --- a/swagger-spec/introduction/versioning.yaml +++ b/swagger-spec/introduction/versioning.yaml @@ -58,6 +58,38 @@ get: the versions must match exactly or a 409 Conflict response will be returned (i.e. one does not take precedence over the other). + + #### CHANGELOG + + `v2.1` + + + Pagination links conform to JSON API specification, i.e. `meta` information was pulled out of the `links` object and placed in a top-level `meta` object. + + + Deprecate the `node_links` field in the **Node** and **Registration** serializers in favor of `linked_nodes` and `linked_registrations`. + + + `v2.2` + + + Modify institution nodes list so that affiliated components are also returned from `/v2/institutions//nodes/`. + + + Ensure all existing date fields are standardized on UTC. + + + `v2.3` + + + Handle merged users more correctly on `/v2/users/`. + + + `v2.4` + + + Deprecate the `parents` field in the **Taxonomies** serializer. + + + Deprecate the following fields in the **Preprint Provider** serializer: + + `social_facebook`, `social_instagram`, and `social_twitter` + + `banner_path`, `logo_path`, and `header_text` + + `email_contact` + + operationId: versioning tags: - Introduction diff --git a/swagger-spec/nodes/definition.yaml b/swagger-spec/nodes/definition.yaml index 2b3eaac741a..1a4ac122514 100644 --- a/swagger-spec/nodes/definition.yaml +++ b/swagger-spec/nodes/definition.yaml @@ -167,7 +167,7 @@ properties: node_links: type: string readOnly: true - description: 'A link to the list of nodes that are linked to the current node. This endpoint is deprecated as of verson 2.1; use the linked_nodes endpoint instead.' + description: 'A link to the list of nodes that are linked to the current node. This field is deprecated as of verson 2.1; use the linked_nodes link instead.' parent: type: string readOnly: true diff --git a/swagger-spec/preprint_providers/definition.yaml b/swagger-spec/preprint_providers/definition.yaml index b1820615a19..a39360a92bd 100644 --- a/swagger-spec/preprint_providers/definition.yaml +++ b/swagger-spec/preprint_providers/definition.yaml @@ -18,7 +18,7 @@ properties: social_instagram: type: string readOnly: true - description: 'The preprint provider''s Instagram account ID.' + description: 'The preprint provider''s Instagram account ID. This field is deprecated as of verson 2.4.' advisory_board: type: string readOnly: true @@ -30,11 +30,11 @@ properties: banner_path: type: string readOnly: true - description: 'A static path to the preprint provider''s banner image.' + description: 'A static path to the preprint provider''s banner image. This field is deprecated as of verson 2.4.' logo_path: type: string readOnly: true - description: 'A static path to the preprint provider''s logo image.' + description: 'A static path to the preprint provider''s logo image. This field is deprecated as of verson 2.4.' subjects_acceptable: type: string readOnly: true @@ -46,11 +46,11 @@ properties: social_facebook: type: string readOnly: true - description: 'The preprint provider''s Facebook account ID.' + description: 'The preprint provider''s Facebook account ID. This field is deprecated as of verson 2.4.' email_contact: type: string readOnly: true - description: 'The preprint provider''s contact email address.' + description: 'The preprint provider''s contact email address. This field is deprecated as of verson 2.4.' example: type: string readOnly: true diff --git a/swagger-spec/registrations/definition.yaml b/swagger-spec/registrations/definition.yaml index f3b44d555b8..d8360ee7521 100644 --- a/swagger-spec/registrations/definition.yaml +++ b/swagger-spec/registrations/definition.yaml @@ -187,6 +187,10 @@ properties: type: string readOnly: true description: 'A link to the list of nodes that are linked to this registration.' + node_links: + type: string + readOnly: true + description: 'A link to the list of nodes that are linked to this registration. This field is deprecated as of verson 2.1; use the linked_nodes link instead.' parent: type: string readOnly: true diff --git a/swagger-spec/taxonomies/definition.yaml b/swagger-spec/taxonomies/definition.yaml index 61325e2d64a..2d28b62463c 100644 --- a/swagger-spec/taxonomies/definition.yaml +++ b/swagger-spec/taxonomies/definition.yaml @@ -40,7 +40,7 @@ properties: items: type: string readOnly: true - description: 'An array of links to to this taxonomy''s parents' + description: 'An array of links to to this taxonomy''s parents. This field is deprecated as of verson 2.4.' self: type: string format: URL diff --git a/swagger-spec/users/list.yaml b/swagger-spec/users/list.yaml index 06407c5a774..d4813971422 100644 --- a/swagger-spec/users/list.yaml +++ b/swagger-spec/users/list.yaml @@ -8,6 +8,10 @@ get: The subroute `/users/me/` is a special endpoint that always points to the currently logged-in user. + #### Versioning + + As of version `2.3`, merged users will not be returned from this endpoint. + #### Returns Returns a JSON object containing `data` and `links` keys. From 5262f9f51859b771e2302780b1b0169a03f6ef6f Mon Sep 17 00:00:00 2001 From: Casey Rollins Date: Tue, 20 Jun 2017 09:36:16 -0400 Subject: [PATCH 7/9] Add testing server note (#66) --- src/main/javascript/view/OperationView.js | 3 +- swagger-spec/introduction/testing.yaml | 34 +++++++++++++++++++++++ swagger-spec/swagger.yaml | 3 ++ 3 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 swagger-spec/introduction/testing.yaml diff --git a/src/main/javascript/view/OperationView.js b/src/main/javascript/view/OperationView.js index a5255465c93..3a4ce9db294 100644 --- a/src/main/javascript/view/OperationView.js +++ b/src/main/javascript/view/OperationView.js @@ -16,7 +16,8 @@ SwaggerUi.Views.OperationView = Backbone.View.extend({ 'Introduction', 'General Usage', 'Actions', 'Attribute Validation', 'Authentication', 'Create/Update Requests', 'Embedding', 'Entities', 'Entity Collections', 'Enum Fields', - 'Errors', 'Error Codes', 'Filtering', 'Pagination', 'Versioning' + 'Errors', 'Error Codes', 'Filtering', 'Pagination', 'Testing', + 'Versioning' ]; opts = opts || {}; diff --git a/swagger-spec/introduction/testing.yaml b/swagger-spec/introduction/testing.yaml new file mode 100644 index 00000000000..074f3b0e9c4 --- /dev/null +++ b/swagger-spec/introduction/testing.yaml @@ -0,0 +1,34 @@ +get: + summary: Testing + description: >- + + #### Testing Server + + The test-* subdomains of the osf are intended to match, at any given time, the current production environment of the Open Science Framework. + + + 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. + + + The test servers linked below are primarily for developing your API application on a stable system. + + + https://test.osf.io/ + + + https://test-api.osf.io/v2/ + + #### Ephemerality Notice + + Expect the server to be down from time to time while we update software, and don't expect that anything you create on here to exist long-term. + + + While this is more stable than a staging server, we won't necessarily run data migrations if anything major happens to our database schema, so we may clear out the data on the test servers periodically. + + operationId: testing + tags: + - Introduction + responses: + '200': + description: OK diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index a44241720b3..65121fc032d 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -63,6 +63,9 @@ paths: /pagination/: $ref: 'introduction/pagination.yaml' + /testing/: + $ref: 'introduction/testing.yaml' + /versioning/: $ref: 'introduction/versioning.yaml' From 515b7cc6d753dbba3abc9cc16311bfcb1000f410 Mon Sep 17 00:00:00 2001 From: Casey Rollins Date: Tue, 20 Jun 2017 09:40:38 -0400 Subject: [PATCH 8/9] Document sparse fieldsets (#67) --- src/main/javascript/view/OperationView.js | 2 +- swagger-spec/introduction/pagination.yaml | 2 +- .../introduction/sparse_fieldsets.yaml | 50 +++++++++++++++++++ swagger-spec/swagger.yaml | 3 ++ 4 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 swagger-spec/introduction/sparse_fieldsets.yaml diff --git a/src/main/javascript/view/OperationView.js b/src/main/javascript/view/OperationView.js index 3a4ce9db294..f4b39054abf 100644 --- a/src/main/javascript/view/OperationView.js +++ b/src/main/javascript/view/OperationView.js @@ -17,7 +17,7 @@ SwaggerUi.Views.OperationView = Backbone.View.extend({ 'Attribute Validation', 'Authentication', 'Create/Update Requests', 'Embedding', 'Entities', 'Entity Collections', 'Enum Fields', 'Errors', 'Error Codes', 'Filtering', 'Pagination', 'Testing', - 'Versioning' + 'Sparse Fieldsets', 'Versioning' ]; opts = opts || {}; diff --git a/swagger-spec/introduction/pagination.yaml b/swagger-spec/introduction/pagination.yaml index c7d414016ad..d9eeb01a016 100644 --- a/swagger-spec/introduction/pagination.yaml +++ b/swagger-spec/introduction/pagination.yaml @@ -1,7 +1,7 @@ get: summary: Pagination description: >- - All entity collection endpoints respond to the `page` query parameter behavior as described in the [JSON-API pagination spec](http://jsonapi.org/format/1.0/#crud). + All entity collection endpoints respond to the `page` query parameter as described in the [JSON-API spec](http://jsonapi.org/format/#fetching-pagination). However, links to the first, last, previous, and next pages of results are provided in the `links` key of the response, diff --git a/swagger-spec/introduction/sparse_fieldsets.yaml b/swagger-spec/introduction/sparse_fieldsets.yaml new file mode 100644 index 00000000000..9db194a47e2 --- /dev/null +++ b/swagger-spec/introduction/sparse_fieldsets.yaml @@ -0,0 +1,50 @@ +get: + summary: Sparse Fieldsets + description: >- + All endpoints respond to the `fields` query parameter as described in the [JSON-API spec](http://jsonapi.org/format/#fetching-sparse-fieldsets). + + #### Basic Usage + + When making a request to an endpoint that returns a serialized object of some `type`, you can specify `fields[]=` to receive a subset of the object's fields in the response. + + + For example, the request below will serialize only the `title` attribute and `children` relationship for each node in the response. + + + https://api.osf.io/v2/nodes/?fields[nodes]=title,children + + + Sparse fieldsets can be used to restrict both attribute and relationship fields. + Note that top-level objects (such as `type`, `id`, `attributes`, `relationships`, and `links`) will always be serialized and cannot be excluded. + + #### Advanced Usage + + Sparse fieldsets can be used to restrict any entity returned in the response. + + + For example, the request below will serialize only the `full_name` attribute for each user (auto-embedded by the `embed=contributors` query parameter), and the `title` attribute for each node. + + + https://api.osf.io/v2/nodes/?fields[nodes]=title,contributors&embed=contributors&fields[users]=full_name + + + When using sparse fieldsets and embeds in the same request, fields that are being embedded must also be included in `fields[type]`, or the embed will be invalid. + + + A request to embed contributors and restrict nodes to only return the `title` attribute should have the form: + + + https://api.osf.io/v2/nodes/?embed=contributors&fields[nodes]=title,contributors + + + **NOT** + + + https://api.osf.io/v2/nodes/?embed=contributors&fields[nodes]=title + + operationId: sparse_fieldsets + tags: + - Introduction + responses: + '200': + description: OK diff --git a/swagger-spec/swagger.yaml b/swagger-spec/swagger.yaml index 65121fc032d..44fc5f2d34b 100644 --- a/swagger-spec/swagger.yaml +++ b/swagger-spec/swagger.yaml @@ -63,6 +63,9 @@ paths: /pagination/: $ref: 'introduction/pagination.yaml' + /sparse_fieldsets/: + $ref: 'introduction/sparse_fieldsets.yaml' + /testing/: $ref: 'introduction/testing.yaml' From 7d06f4dfcaa5e2b3a0c5e7e7fc1c400bf65a3301 Mon Sep 17 00:00:00 2001 From: Casey Rollins Date: Fri, 23 Jun 2017 15:57:58 -0400 Subject: [PATCH 9/9] Reword sparse fieldset docs. Add note from JSON API spec. (#68) --- src/main/html/css/index.css | 9 +++++++++ swagger-spec/introduction/sparse_fieldsets.yaml | 14 ++++++++++++-- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/src/main/html/css/index.css b/src/main/html/css/index.css index de8cafbb835..79b41c207a1 100644 --- a/src/main/html/css/index.css +++ b/src/main/html/css/index.css @@ -1586,6 +1586,15 @@ code { border-radius: 4px; border: 1px solid #f0f4f7; } +blockquote { + padding: 10px 20px; + margin: 10px 0; + line-height: 1.8; + background: #f9f9f9; + color: #838991; + border-left: 0.25em solid #dfe2e5; + font-size: 14px; +} kbd { padding: 2px 4px; font-size: 90%; diff --git a/swagger-spec/introduction/sparse_fieldsets.yaml b/swagger-spec/introduction/sparse_fieldsets.yaml index 9db194a47e2..05bbb024c26 100644 --- a/swagger-spec/introduction/sparse_fieldsets.yaml +++ b/swagger-spec/introduction/sparse_fieldsets.yaml @@ -1,8 +1,17 @@ get: summary: Sparse Fieldsets - description: >- + description: | All endpoints respond to the `fields` query parameter as described in the [JSON-API spec](http://jsonapi.org/format/#fetching-sparse-fieldsets). + + From the specification: + +
+

A client MAY request that an endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter.

+

The value of the fields parameter MUST be a comma-separated (U+002C COMMA, “,”) list that refers to the name(s) of the fields to be returned.

+

If a client requests a restricted set of fields for a given resource type, an endpoint MUST NOT include additional fields in resource objects of that type in its response.

+
+ #### Basic Usage When making a request to an endpoint that returns a serialized object of some `type`, you can specify `fields[]=` to receive a subset of the object's fields in the response. @@ -28,7 +37,8 @@ get: https://api.osf.io/v2/nodes/?fields[nodes]=title,contributors&embed=contributors&fields[users]=full_name - When using sparse fieldsets and embeds in the same request, fields that are being embedded must also be included in `fields[type]`, or the embed will be invalid. + Any field specified in another query parameters used by the serializer (e.g. `embed`) must also be included in the sparse fieldset. + For example, fields that are being embedded on the sparse type (e.g. `nodes`) must also be included in `fields[]` when using embeds, or the embed will be invalid. A request to embed contributors and restrict nodes to only return the `title` attribute should have the form: