Skip to content

Latest commit

 

History

History
85 lines (52 loc) · 3.86 KB

README.md

File metadata and controls

85 lines (52 loc) · 3.86 KB
Raw

APIs development guidelines

Concept

Common REST API specifications and models (defined as openAPI- or JSON-schemas) are defined in a central location api/specs to allow for design-first development.

Standards

The oSparc platform uses the following standards:

In every service:

The api is defined in

  • /api/Makefile bundles oas-parts into openapi.yaml and validates it
  • /api/v0
    • /api/v0/openapi.yaml is the output of api/Makefile. DO NOT EDIT MANUALLY. Use instead Makefile
    • /api/v0/oas-parts/* folder contains all parts of the open-api specs as well as json schemas of models. This is the folder that the user shall modify.

In common folder:

/api/specs/                                  # base folder

/api/specs/common/                           # common api/specs/schemas base folder
/api/specs/common/schemas/                   # sub folder for schemas
/api/specs/common/schemas/health_check.yaml  # openapi encoded common schema
/api/specs/common/schemas/node-meta.json     # jsonschema encoded common schema
/api/specs/common/schemas/v1/error.yaml      # openapi encoded common schema for version 1
/api/specs/common/schemas/v2/error.yaml      # openapi encoded common schema for version 2

/tests/                                 # python tests folder to check schemas validity
/tests/requirements.txt                 # requirements for python tests

Organization

Openapi specifications file

Each API is defined within a file openapi.yaml in YAML format. The file shall be located in the a subfolder named after the service/package and the major version subfolder.

Version subfolder

For initial development, the version shall be 0.1.0 and the subfolder v0 For release, the version shall start from 1.0.0 and subfolder v1. The subolder digit corresponds to the version major digits. It shall be modified only when changes are not backwards compatible (e.g. changing a return value, removing parameters or resource, ...).

Schemas in separate files

Schemas shall always be defined in separate files.

Schemas format shall be either OpenAPI v3 or JSON schema Draft#7.

If these schemas are pertinent only to the current API they shall be contained together with the openapi specifications file inside a schemas subfolder. If these schemas are common with other APIs they should be located in the /common/schemas subfolder.

Versioning common schemas

NOTE: If common schemas need backward incompatible changes, then a new major version of this specific common schema is necessary and all APIs that rely on this specific schema will need to be upgraded. In that case, a version subfolder shall be added in the /common/ subfolder and the relevant schemas shall be moved there.

Schemas defined with JSONSchema format that are used together with OpenAPI

Mixing JSONSchema with OpenAPI schema needs some additional steps:

  1. Define the JSONSchema schema.
  2. Convert the JSONSchema formatted file to OpenAPI formatted file using a converter tool.
  3. In the openapi specifications file ref the converted OpenAPI schema file

This is automated in the makefiles as dependencies

references