cernanalysispreservation · ArtemisLav · Apr 6, 2021 · Apr 6, 2021 · Apr 21, 2021 · Apr 7, 2021
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Ivan Goncharov
+Copyright (c) 2019-2021 CERN.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,12 +1,26 @@
-# CAP API Documentation OpenAPI Specification
 
-## Working on specification
-### Install
 
+# CERN Analysis Preservation REST API Documentation
+
+### About
+----
+This is the documentation behind the REST API for [CERN Analysis Preservation](https://analysispreservation.cern.ch/).
+
+Other documentation:
+- [CERN Analysis Preservation Docs](https://analysispreservation.cern.ch/docs/general/)
+- [CERN Analysis Preservation Client](https://analysispreservation.cern.ch/docs/cli/)
+
+If you need help or have a question about the API Documentation, please contact us via our [email]([email protected]).
+
+# OpenAPI Specification
+
+### Install
+---
 1. Install [Node JS](https://nodejs.org/)
 2. Clone repo and run `npm install` in the repo root
 
 ### Usage
+---
 
 #### `npm start`
 Starts the development server.

diff --git a/spec/components/securitySchemes/Access Token.yaml b/spec/components/securitySchemes/Access Token.yaml
@@ -2,24 +2,22 @@ type: apiKey
 in: query
 name: access_token
 description: >
-  > Your access token will allow you to use the service in the same way in which
-  you may use it if you log in on the web portal. You will have the same
-  permissions unless specified otherwise creation of the token. This implies
-  that anyone who has this token can log in as yourself to the service. Do not
-  share your personal access token with anyone else, and only use it with HTTPS!
+  Your access token will allow you to use the service in the same way you would
+  use it through the web portal. It gives full access to your account and anyone who has this token can log in as yourself to the service.
+
+
+  Do not share your personal access token with anyone else, and only use it with HTTPS.
 
 
   To get an access token, you will need to log in on the web portal and [create
-  one](https://analysispreservation.cern.ch/settings), as shown below.
+  one](https://analysispreservation.cern.ch/settings) by clicking on `Add Token` as shown below.
+
 
-  In this dialog, `scopes` lets you define permissions for the token which by
-  default only include read access to your drafts and records.
+  ![create_token](https://github.com/cernanalysispreservation/analysispreservation.cern.ch/raw/master/docs/_static/fig_token_new.png)
 
 
-  ![create_token](https://cernanalysispreservation.readthedocs.io/en/latest/_images/fig_token.png)
+  Once you have created your token, you can see the generated key in the settings page
+  where your list of tokens is stored. It is also possible to revoke a token.
 
 
-  Clicking "Submit" will generate and show your personal token in the browser.
-  Please copy it to a safe place on your computer, as it is not stored on the
-  portal and you will not be able to retrieve the same token again in the
-  future.
+  ![your_list_of_tokens](https://github.com/cernanalysispreservation/analysispreservation.cern.ch/raw/master/docs/_static/fig_token_new2.png)
diff --git a/spec/openapi.yaml b/spec/openapi.yaml
@@ -2,26 +2,24 @@ openapi: 3.0.0
 info:
   version: 1.0.0
   title: CERN Analysis Preservation REST API
-  termsOfService: 'https://analysispreservation.cern.ch/terms/'
   contact:
     email: [email protected]
-    url: 'https://analysispreservation.cern.ch/about'
-  license:
-    name: Apache 2.0
-    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+    url: 'https://analysispreservation.cern.ch'
   x-logo:
     url: >-
       https://github.com/cernanalysispreservation/cap-api-docs/raw/master/web/CAP_API_docs.png
   description: >
+
+    CERN Analysis Preservation (CAP) is a service developed at the European Organization for Nuclear Research (CERN) to support researchers in preserving and documenting the various components of their physics analyses, so that they are reusable and understandable in the future.
+
     CERN Analysis Preservation offers a REST API to access the service
     independently from the web interface. This allows users to automate specific
     tasks or create their own data interface, using simple HTTP calls.
 
 
     # Introduction
 
-    CERN Analysis Preservation provides a RESTful API, built on HTTP. It tries
-    to provide a predictable interface, that includes:
+    CERN Analysis Preservation provides a RESTful API, built on HTTP. It provides a predictable interface, that includes:
 
     * resource URLs,
 
@@ -33,8 +31,8 @@ info:
     You can use your favorite HTTP/REST library for your programming language to
     use CAP's API, or you can use one of our SDKs (CLI clients), currently
     available in Python. Every action from our app is implemented using REST
-    endpoints, all of which are documented and available, in order to bea easily
-    accessible for automations and integrations into specific workflowsor
+    endpoints, all of which are documented and available, in order to be easily
+    accessible for automations and integrations into specific workflows or
     data-related apps.
 
 
@@ -54,21 +52,21 @@ info:
 
     <!-- ReDoc-Inject: <security-definitions> -->
 externalDocs:
-  description: Click here if you are looking for our developement documentation.
-  url: 'https://cernanalysispreservation.readthedocs.io'
+  description: Click here if you are looking for our general documentation.
+  url: 'https://analysispreservation.cern.ch/docs/general/'
 tags:
   - name: Deposits
-    description: The Deposit resource is used for uploading and editing records on CAP
+    description: The Deposit resource is used for uploading and editing records on CAP.
   - name: Records
     description: >
       The Record resource is used for fetching and searching published records
       on CAP. Create deposit
   - name: Files
     description: >
-      The Files resource is used for uploading files and attach them to
-      records/deposits
+      The Files resource is used for uploading files and attachinging them to
+      records/deposits.
 
-      The following type of upload are possible:
+      The following types of uploads are possible:
         * Local files
         * Git repos
         * URL linked files
@@ -81,7 +79,7 @@ tags:
   - name: Services
     description: Operations about services
   - name: User
-    description: Operations about user
+    description: Operations about users
 security:
   - Access Token: []
 servers:

diff --git a/spec/paths/deposits.yaml b/spec/paths/deposits.yaml
@@ -6,12 +6,10 @@ post:
 
 
     > JSON Schemas and analysis types (`$ana_type`) depend on the access rights
-    you have and mainly\
-
-    correspond to the CERN collaboration you are part of (***ALICE, ATLAS, CMS,
+    you have and mainly correspond to the CERN collaboration you are part of (***ALICE, ATLAS, CMS,
     LHCb***).\
 
-    To get the list of available schemas you can call the 
+    To get the list of available schemas you can call the
   tags:
     - Deposits
   requestBody:
@@ -59,8 +57,8 @@ post:
 get:
   summary: List all deposits/drafts
   description: >-
-    List all deposits for the currently authenticated user. At least `read`
-    access is needed to query a record
+    List all deposits for the currently authenticated user.
+    > At least `read` access is needed to query a record.
   tags:
     - Deposits
   parameters:

diff --git a/spec/paths/deposits@{depid}.yaml b/spec/paths/deposits@{depid}.yaml
@@ -11,8 +11,8 @@ get:
     - Deposits
   summary: Get deposit by ID
   description: |
-    Retrieve a deposit/draft resource by the `deposit_id`
-    > You need to have at least 'read' access
+    Retrieve a deposit/draft resource using `deposit_id`.
+    > You need to have at least 'read' access.
   operationId: get_deposit
   responses:
     '200':
@@ -34,7 +34,7 @@ put:
   tags:
     - Deposits
   summary: Update a deposit
-  description: Update a deposit/draft resource
+  description: Update a deposit/draft resource.
   operationId: depositUpdate
   requestBody:
     content:
@@ -45,8 +45,8 @@ put:
           title: My new title
           abstract: Already commited/saved abstract desciption
     description: |
-      A JSON object that will replace the `metadata` field of the resource
-      > It should validate against the specified `$schema` of the resource
+      A JSON object that will replace the `metadata` field of the resource.
+      > It should validate against the specified `$schema` of the resource.
     required: true
   responses:
     '200':
@@ -70,7 +70,7 @@ patch:
     - Deposits
   summary: Patch a deposit
   description: >
-    Update a deposit/draft resource with a [JSON Patch](http://jsonpatch.com/)
+    Update a deposit/draft resource with a [JSON Patch](http://jsonpatch.com/).
 
 
     ### What is JSON Patch?
@@ -87,7 +87,7 @@ patch:
 
 
     JSON Patch is specified in [RFC 6902](http://tools.ietf.org/html/rfc6902)
-    from the IETF.
+    by the IETF.
 
 
     ### Simple example
@@ -135,9 +135,9 @@ patch:
           value: Gen Test
     description: >
       A [JSON Patch](http://jsonpatch.com/) object that will update/patch on top
-      of the `metadata` of the resource
+      of the `metadata` of the resource.
 
-      > It should validate against the specified `$schema` of the resource
+      > It should validate against the specified `$schema` of the resource.
     required: true
   responses:
     '200':

diff --git a/spec/paths/deposits@{depid}@[email protected] b/spec/paths/deposits@{depid}@[email protected]
@@ -11,8 +11,8 @@ post:
     - Deposits
   summary: Clone/duplicate a draft
   description: |
-    Retrieve a draft records by the `deposit_id`
-    > You need to have at least 'read' access
+    Retrieve a draft record using `deposit_id`.
+    > You need to have at least 'read' access.
   operationId: cloneDeposit
   responses:
     '200':

diff --git a/spec/paths/deposits@{depid}@[email protected] b/spec/paths/deposits@{depid}@[email protected]
@@ -9,12 +9,12 @@ parameters:
 post:
   tags:
     - Deposits
-  summary: Edit published deposit
+  summary: Edit a published deposit
   description: >
     To be able to **edit** an already `published` deposit, you should first
     change it's status to `draft`. Only then you can
     [update](#operation/depositUpdate) or [patch](#operation/depositPatch)
-    depending on your needs 
+    depending on your needs.
   operationId: editDeposit
   responses:
     '200':

diff --git a/spec/paths/deposits@{depid}@[email protected] b/spec/paths/deposits@{depid}@[email protected]
@@ -11,8 +11,8 @@ post:
     - Deposits
   summary: Add/remove permissions
   description: |
-    Add or remove `user` and `e-group` access to the resource
-    > You need to have 'admin' rights for the deposit to change permissions
+    Add or remove `user` and `e-group` access for a resource.
+    > You need to have 'admin' rights for the deposit to be able to change permissions.
   operationId: permissionsDeposit
   responses:
     '200':

diff --git a/spec/paths/deposits@{depid}@[email protected] b/spec/paths/deposits@{depid}@[email protected]
@@ -12,7 +12,7 @@ post:
   summary: Publish to collaboration
   description: >
     Create a new version of the document and make it public to your
-    collaboration
+    collaboration.
   operationId: publishDeposit
   responses:
     '200':

diff --git a/spec/paths/deposits@{depid}@[email protected] b/spec/paths/deposits@{depid}@[email protected]
@@ -26,13 +26,13 @@ post:
   summary: Upload files/data
   description: |
     Upload files/data to your analysis, in a specified deposit record.
-    The following type of uploads are possible:
+    The following types of uploads are possible:
       * Local files
       * Git repos
       * URL linked files
 
     The API differentiates between whole repos (saved as .tar) and single files
-    from repos, so the parameter "type" is necessary.
+    from repos, so the parameter `type` is necessary.
   operationId: uploadDeposit
   responses:
     '200':

diff --git a/spec/paths/deposits@{depid}@files.yaml b/spec/paths/deposits@{depid}@files.yaml
@@ -11,7 +11,7 @@ get:
     - Deposits
   summary: Get deposit files
   description: |
-    Retrieve all files that are associated with the draft record
+    Retrieve all files that are associated with a draft record.
   responses:
     '200':
       description: List of files
@@ -28,10 +28,10 @@ get:
 post:
   tags:
     - Deposits
-  summary: Upload local files
+  summary: Upload local files.
   description: |
-    Retrieve a draft records by the `deposit_id`
-    > You need to have at least 'read' access
+    Retrieve a draft record using `deposit_id`
+    > You need to have at least 'read' access.
   operationId: filesDeposit
   responses:
     '200':

diff --git a/spec/paths/jsonschemas.yaml b/spec/paths/jsonschemas.yaml
@@ -3,8 +3,8 @@ get:
     - JSON Schemas
   summary: Get a list of available JSON Schemas
   description: >-
-    List of the available JSON schemas. They can be used to create an analysis
-    record
+    List of the available JSON Schemas. They can be used to create an analysis
+    record.
   operationId: getJSONSchemas
   responses:
     '200':
@@ -26,11 +26,11 @@ get:
 post:
   tags:
     - JSON Schemas
-  summary: Create a new JSON Schemas
+  summary: Create a new JSON schema
   description: >
-    Create a new JSON schemas. Add your customized schemas for records and
+    Create a new JSON Schema. Add your customized schemas for records and
     deposits, your corresponding UI form options and ES search mapping for
-    better indexing
+    better indexing.
   operationId: createJSONSchemas
   requestBody:
     content:
@@ -41,7 +41,7 @@ post:
           simple:
             $ref: '#/components/examples/JSONSchemaResource'
     description: |
-      A JSON object that will populate the `Schema` resource
+      A JSON object that will populate the `Schema` resource.
     required: true
   responses:
     '200':

diff --git a/spec/paths/jsonschemas@{name}.yaml b/spec/paths/jsonschemas@{name}.yaml
@@ -9,7 +9,7 @@ get:
   tags:
     - JSON Schemas
   summary: Get latest version by name
-  description: Retrieve the latest JSON Schemas for the specified `name`
+  description: Retrieve the latest JSON Schema for a specified `name`.
   operationId: getLatestByName
   responses:
     '200':