General API Conventions

General Applicable Open API Conventions

Specification Standard

The API complies with Open API 3.0.

Restful Principles


Resources are coded as URI (e.g. http://domain/api/pets). Resources should be nouns (verbs are bad)


Users interact with resources through HTTP request verbs. The PDS API uses GET and POST:

  • GET is relevant to get resource representation from the API when the extraction criteria is simple.

  • POST, in a read-only context, is relevant to provide the API with complex request criteria.

Future iterations of the API will transform it to be an idempotent REST API, utilizing GET, PUT, DELETE, HEAD, OPTIONS and TRACE HTTP methods.

Resource Representation

When a HTTP request verb (e.g. GET, POST, etc.) is applied to a resource (e.g. http://domain/api/pets) he/she gets a resource representation.

Many flavors of representations are possible to be returned from a single resource. For example: subsets of a whole, formats, versions, etc…

The resource representation should be self-described as much as possible.

They should be wrapped in envelopes which prevent from vulnerabilities linked to the direct access to json arrays in javascript code (see A response with this format is fine:

   "summmary": {"..."},
   "data": ["..."]

Other Conventions

Beyond the OpenAPI standard, there are multiple options regarding general design of an API. We primarily use the following source which is very complete and not too dogmatic:

Some peer web API specifications are also considered as references for the design for the PDS API specification:

URL Resource Naming: Case

Kebab-case (lower case and hyphens ‘-’ used to fill the spaces in) is used for url resource naming.

For example:

(for the rationale see this stackoverflow discussion

URL Resource Naming: Plural vs Singular

Resources are named plural or singular depending on the use case.

Plural are used when the resources is a collection the user will subset from, for example `/pets/scooby-doo` or `/planets/mars` or ‘/users/user-id’ or ‘collections?q=…’’

Singular are used when the resource is accessed as one. For example ‘/profile’ to access the profile of the current user.

See this post for more details.

URL Resource Naming: API Versioning

The API will have versions and the deployed versions are likely to be heterogeneous in the PDS system.

Two options have been considered to manage versions (see :

  • Version in the URL, e.g.

  • Content negotiation headers (e.g. Accept: application/vnd.example+json;version=1.0)

To keep things as simple as possible, content negotiation will not be used for version management. A server API implementation will implement a single version of the API definition.


  • We advise to use the version in the URL of the API when it is deployed, although it is not part of the API definition.

  • The version is mandatory in the resource representations (result of a request)


The query parameters for pagination are:




Index of first item returned in the response


Maximum number of item expected in the response