GuidesAPI Reference
DocumentationLog In

REST API conventions

Our REST APIs use the standard HTTP Method and URL naming conventions.
For your reference https://wiki.onap.org/display/DW/RESTful+API+Design+Specification, https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/

Operations

  • GET operations are idempotent. URLs to retrieve collections of entities are based on the type of entity. For example, /eth2/v1/validators retrieves all validators. To retrieve details of a specific entity, an identifier for the desired entity is appended to the path, e.g. /eth2/v1/validators/abc123.

  • POST operations are not expected to be idempotent (but duplicate operations are detected and ignored where appropriate). URLs to create entities are based on the type of entity. For example, /eth2/v1/validators is used to create validators.

  • PUT operations are idempotent and are generally used to update properties of an existing entity.

  • DELETE operations generally only support deleting a single specific entity, e.g. /eth2/v1/validators/abc123.

  • PUT and POST operations that have a required payload necessitate the payload to be passed in the Body as a json object (content-type: application/json).

Responses

All responses, except certain server errors, are returned as JSON in the Body of the response.

When successful, the HTTP Response Code is 200 and the response data is in the Body. When it fails, the HTTP Response Code reflects the type of error; if the API generates the response, the Body contains a JSON object of the form: { ‘error’: ‘message’ }

See Errors for more details on API errors.