General API Conventions¶

Reference Documents¶

Several websites and documents were used as references for designing this API and the accompanying guidelines, including:

General Applicable Open API Conventions¶

Specification Standard¶

The API complies with Open API 3.0.

Restful Principles¶

Resources¶

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

Verbs¶

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 https://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx/). 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: https://www.moesif.com/blog/api-guide/api-design-guidelines/

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:

`discipline-nodes` in http://pds.nasa.gov/api/references/0.1/discipline-nodes

(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 https://restfulapi.net/versioning/ :

Version in the URL, e.g. pds.nasa.gov/api/search/1/
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.

However:

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)

Pagination/Sort¶

The query parameters for pagination are:

Parameter	Description
start	Index of first item returned in the response
limit	Maximum number of item expected in the response

See https://www.moesif.com/blog/technical/api-design/REST-API-Design-Filtering-Sorting-and-Pagination/