From e67ed45c58ef730fc8b3f0952c26910cf04321bf Mon Sep 17 00:00:00 2001 From: Artemis Lavasa Date: Tue, 6 Apr 2021 21:57:53 +0200 Subject: [PATCH 1/4] docs: content quality checks Signed-off-by: Artemis Lavasa --- .../securitySchemes/Access Token.yaml | 8 +++--- spec/openapi.yaml | 28 +++++++++---------- spec/paths/deposits.yaml | 10 +++---- spec/paths/deposits@{depid}.yaml | 18 ++++++------ .../paths/deposits@{depid}@actions@clone.yaml | 4 +-- spec/paths/deposits@{depid}@actions@edit.yaml | 4 +-- .../deposits@{depid}@actions@permissions.yaml | 4 +-- .../deposits@{depid}@actions@publish.yaml | 2 +- .../deposits@{depid}@actions@upload.yaml | 4 +-- spec/paths/deposits@{depid}@files.yaml | 8 +++--- spec/paths/jsonschemas.yaml | 12 ++++---- spec/paths/jsonschemas@{name}.yaml | 2 +- spec/paths/jsonschemas@{name}@{version}.yaml | 14 +++++----- spec/paths/records.yaml | 6 ++-- spec/paths/users@{username}.yaml | 2 +- .../workflows@reana@all@record@{pid}.yaml | 2 +- 16 files changed, 62 insertions(+), 66 deletions(-) diff --git a/spec/components/securitySchemes/Access Token.yaml b/spec/components/securitySchemes/Access Token.yaml index b3d43c5..d181083 100644 --- a/spec/components/securitySchemes/Access Token.yaml +++ b/spec/components/securitySchemes/Access Token.yaml @@ -2,11 +2,11 @@ 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 + > Your access token will allow you to use the service in the same way you would + use it through the web portal. You will have the same + permissions unless specified otherwise during the 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! + 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 diff --git a/spec/openapi.yaml b/spec/openapi.yaml index 5ac49dd..c28a552 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -2,17 +2,16 @@ openapi: 3.0.0 info: version: 1.0.0 title: CERN Analysis Preservation REST API - termsOfService: 'https://analysispreservation.cern.ch/terms/' contact: email: analysis-preservation-support@cern.ch - 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. @@ -20,8 +19,7 @@ info: # 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: externalDocs: - description: Click here if you are looking for our developement documentation. + description: Click here if you are looking for our development documentation. url: 'https://cernanalysispreservation.readthedocs.io' 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 index 59e4c47..80e8ab6 100644 --- 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 index 1a8de93..51e1f1e 100644 --- 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}@actions@clone.yaml b/spec/paths/deposits@{depid}@actions@clone.yaml index b622e78..ec4a8ca 100644 --- a/spec/paths/deposits@{depid}@actions@clone.yaml +++ b/spec/paths/deposits@{depid}@actions@clone.yaml @@ -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}@actions@edit.yaml b/spec/paths/deposits@{depid}@actions@edit.yaml index 76b5f45..2b46954 100644 --- a/spec/paths/deposits@{depid}@actions@edit.yaml +++ b/spec/paths/deposits@{depid}@actions@edit.yaml @@ -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}@actions@permissions.yaml b/spec/paths/deposits@{depid}@actions@permissions.yaml index fbf5608..0b7f8ff 100644 --- a/spec/paths/deposits@{depid}@actions@permissions.yaml +++ b/spec/paths/deposits@{depid}@actions@permissions.yaml @@ -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}@actions@publish.yaml b/spec/paths/deposits@{depid}@actions@publish.yaml index 2c3cf38..ad57b09 100644 --- a/spec/paths/deposits@{depid}@actions@publish.yaml +++ b/spec/paths/deposits@{depid}@actions@publish.yaml @@ -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}@actions@upload.yaml b/spec/paths/deposits@{depid}@actions@upload.yaml index 813fee6..20ff3f5 100644 --- a/spec/paths/deposits@{depid}@actions@upload.yaml +++ b/spec/paths/deposits@{depid}@actions@upload.yaml @@ -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 index 022f118..6721546 100644 --- 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 index f693361..0e690cc 100644 --- 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 index 9cce981..1e389fa 100644 --- 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': diff --git a/spec/paths/jsonschemas@{name}@{version}.yaml b/spec/paths/jsonschemas@{name}@{version}.yaml index 4bf01af..ce8d9c9 100644 --- a/spec/paths/jsonschemas@{name}@{version}.yaml +++ b/spec/paths/jsonschemas@{name}@{version}.yaml @@ -15,7 +15,7 @@ get: tags: - JSON Schemas summary: Get schema by name and version - description: Retrieve the latest JSON Schemas for the specified `name` + description: Retrieve the latest JSON Schemas for a specified `name` and `version`. operationId: getSchemaByNameAndVersion responses: '200': @@ -35,11 +35,11 @@ get: put: tags: - JSON Schemas - summary: Update schemas for a specific name and version + summary: Update schemas for a specific name and version, 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: updateSchemaByNameAndVersion requestBody: content: @@ -50,8 +50,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': @@ -72,7 +72,7 @@ delete: tags: - JSON Schemas summary: Remove schemas for a specific name and version - description: Remove schemas for a specific name and version + description: Remove schemas for a specific name and version. operationId: deleteSchemaByNameAndVersion responses: '200': diff --git a/spec/paths/records.yaml b/spec/paths/records.yaml index 766fc3f..e0272b9 100644 --- a/spec/paths/records.yaml +++ b/spec/paths/records.yaml @@ -8,8 +8,8 @@ get: - Search summary: Retrieve a list of records description: >- - Query published records (You need to have at least 'read' access to query - them) + Query published records. + > You need to have at least 'read' access to query them. operationId: get_records parameters: - $ref: '#/components/parameters/query' @@ -57,7 +57,7 @@ post: tags: - Records summary: Create a record - description: Create a record + description: Create a record. operationId: create_record responses: '200': diff --git a/spec/paths/users@{username}.yaml b/spec/paths/users@{username}.yaml index 63f8a0d..63e25d0 100644 --- a/spec/paths/users@{username}.yaml +++ b/spec/paths/users@{username}.yaml @@ -41,7 +41,7 @@ get: put: tags: - User - summary: Updated user + summary: Update user description: This can only be done by the logged in user. operationId: updateUser parameters: diff --git a/spec/paths/workflows@reana@all@record@{pid}.yaml b/spec/paths/workflows@reana@all@record@{pid}.yaml index 08d09cc..d83159f 100644 --- a/spec/paths/workflows@reana@all@record@{pid}.yaml +++ b/spec/paths/workflows@reana@all@record@{pid}.yaml @@ -4,7 +4,7 @@ get: tags: - Workflows summary: Get all the workflows - description: Get all the workflows (created and deleted) from the user + description: Get all the workflows (created and deleted) from the user. operationId: reana_workflow_all responses: '200': From e91c283bb8bc2966419eee6b61db34e78834fa1e Mon Sep 17 00:00:00 2001 From: Artemis Lavasa Date: Tue, 6 Apr 2021 22:57:50 +0200 Subject: [PATCH 2/4] docs: fix url Signed-off-by: Artemis Lavasa --- spec/openapi.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/openapi.yaml b/spec/openapi.yaml index c28a552..1ab8e08 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -52,8 +52,8 @@ info: externalDocs: - description: Click here if you are looking for our development 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. From 143c4ba4d6dc0b870bbc3e4a663f17f576136b60 Mon Sep 17 00:00:00 2001 From: Artemis Lavasa Date: Wed, 21 Apr 2021 14:40:16 +0200 Subject: [PATCH 3/4] docs: update access token * closes #10 Signed-off-by: Artemis Lavasa --- .../securitySchemes/Access Token.yaml | 24 +++++++++---------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/spec/components/securitySchemes/Access Token.yaml b/spec/components/securitySchemes/Access Token.yaml index d181083..0927199 100644 --- 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 you would - use it through the web portal. You will have the same - permissions unless specified otherwise during the 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) From 048bede6acc56ef4f44c22c1cb8db3b28da1868b Mon Sep 17 00:00:00 2001 From: Artemis Lavasa Date: Wed, 7 Apr 2021 16:52:10 +0200 Subject: [PATCH 4/4] docs: fix license, better README Signed-off-by: Artemis Lavasa --- LICENSE | 2 +- README.md | 20 +++++++++++++++++--- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/LICENSE b/LICENSE index d41b8bd..942ab24 100644 --- 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 index 3034f51..dac9030 100644 --- 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](analysis-preservation-support@cern.ch). + +# 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.