Merge branch 'release/0.3.0'

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%;

src/main/javascript/view/OperationView.js

@@ -13,10 +13,11 @@ 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'
+      'Introduction', 'General Usage', 'Actions',
+      'Attribute Validation', 'Authentication', 'Create/Update Requests',
+      'Embedding', 'Entities', 'Entity Collections', 'Enum Fields',
+      'Errors', 'Error Codes', 'Filtering', 'Pagination', 'Testing',
+      'Sparse Fieldsets', 'Versioning'
     ];
 
     opts = opts || {};

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.

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 <token>` as shown in the example below, replacing `<token>` with your token.
+
+        curl -X "GET" "https://api.osf.io/v2/users/me/" \
+        -H "Authorization: Bearer <token>"
+
+    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

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**
 
 

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.

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,
@@ -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.
 

swagger-spec/introduction/sparse_fieldsets.yaml

@@ -0,0 +1,60 @@
+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).
+
+
+    From the specification:
+
+    <blockquote>
+      <p>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.</p>
+      <p>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.</p>
+      <p>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.</p>
+    </blockquote>
+
+    #### Basic Usage
+
+    When making a request to an endpoint that returns a serialized object of some `type`, you can specify `fields[<type>]=<comma,separated,list,of,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
+
+
+    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[<type>]` 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:
+
+
+    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

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

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/<id>/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

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

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 view only link added to the node was anonymous.'
           bucket:
             type: string
             readOnly: true

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

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

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

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:

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:

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