REST Guidelines

Default success code if the document exists.

Bad request

The dynamic path segment containing the identity key has a wrong data format:

{
  "type": "urn:problem-type:belgif:badRequest",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html",
  "status": 400,
  "title": "Bad Request",
  "instance": "urn:uuid:d9e35127-e9b1-4201-a211-2b52e52508df",
  "detail": "The input message is incorrect",
  "issues": [
    {
      "type": "urn:problem-type:belgif:input-validation:schemaViolation",
      "in": "path",
      "name": "employerId",
      "value": "abc",
      "detail": "This value should be numeric"
    }
  ]
}

Not Found

The document resource does not exist.

204 No content should not be used with GET.

Rule: Retrieve partial resource representation [res-repres]

The select query parameter is reserved to return a resource representation with only the specified properties.

The value of this parameter SHOULD follow this BNF grammar:

<selects>            ::= [ <negation> ] <selects_struct>
<selects_struct>     ::= "(" <select_items> ")"
<select_items>       ::= <select> [ "," <select_items> ]
<select>             ::= <select_name> | <selects_substruct>
<selects_substruct>  ::= <select_name> <selects_struct>
<select_name>        ::= <dash_letter_digit> [ <select_name> ]
<dash_letter_digit> ::= <dash> | <letter> | <digit>
<dash>              ::= "-" | "_"
<letter>            ::= "A" | ... | "Z" | "a" | ... | "z"
<digit>             ::= "0" | ... | "9"
<negation>          ::= "!"

Example 14. Select query parameter

GET /employers/93017373?select=(name)

{
  "self": "/employers/93017373?select=(name)",
  "name": "Proximus"
}

Note that parentheses around the value of the select parameter are required, even when selecting a single property.

This notation can also be used for nested properties:

GET /employers/93017373?select=(name,address(street(name,code)))

{
  "self": "/employers/93017373",
  "name": "Proximus",
  "address": {
    "street": {
      "name": "Koning Albert II laan",
      "code": 2177
    }
  }
}

4.3.3. Update

Updating a resource may be done in one of several ways. One and only one of following patterns should be chosen per resource, unless forced by a backwards compatible change.

In order of preference:

use PUT with complete objects to update a resource as long as feasible (i.e. do not use PATCH at all).

This option is preferred when clients are likely to always take into account the entire resource representation. If a client ignores some of a resource’s properties returned by a consultation, they are likely to be omitted from the PUT request and thus lost. This scenario may occur when new properties were added during the API lifecycle. In this case, use of PUT isn’t advised.
Use PATCH with partial objects to only update parts of a resource, whenever possible, using the JSON Merge Patch standard.

JSON Merge Patch is limited however, e.g. it doesn’t allow for an update of a single element of an array. If this proves to be an issue, this might however indicate that the array elements might be better modeled as separate sub-resources.
use POST on a child resource instead of PATCH if the request does not modify the resource in a way defined by the semantics of the media type. See Controller for more information.

Use of the JSON Patch standard, an alternative to JSON Merge Patch, is not recommended, as it proves to be difficult to implement.

Full update

Use PUT when you like to do a complete update of a document resource. All values are replaced by the values submitted by the client. Absent optional values in the request are set to their default value if one is specified in the OpenAPI specification.

Example 15. PUT on a document resource

PUT https://api.socialsecurity.be/demo/v1/employers/93017373 HTTP/1.1

{
    "employerId": 93017373,
    "name": "Belgacom"
}

PUT

/employers/{employerId}

Replace the entire employer resource with the client data. This implies a full update of the resource. Via PUT the client submits new values for all the data.

Request

body

Full representation of the resource to persist.

Parameters

employerId

path-param

employer ID of NSSO uniquely identifying the employer.

Response

body

either empty or resource after update

{
    "employerId": 93017373,
    "name": "Belgacom"
}

Most used response codes

The update is successful and updated resource is returned.

No Content

The update is successful but updated resource is not returned.

Bad request

The input data is not valid according the data schema.

Not Found

The resource does not exist and thus cannot be updated.

Conflict

The client data is in conflict with the data on the server e.g. optimistic locking issues.

Partial update

Rule: JSON Merge patch [doc-patch]

Use PATCH when you like to do a partial update of a document resource.

The PATCH message SHOULD conform to the JSON Merge Patch (RFC 7386) specification:

JSON properties in the request overwrite the ones in the previous resource state
properties with value null in the request are removed from the resource
properties not present in the request are preserved

APIs should support both the media type of JSON merge patch application/merge-patch+json as the generic application/json JSON media type.

Properties that can be removed, must have nullable: true in the OpenAPI 3.0 schema describing the JSON Merge Patch request, which is an exception to [jsn-null]. JSON Merge Patch requests SHOULD be represented by a different schema than other document operations (create, consult or full update), because in a JSON Merge Patch request, required properties may be absent or optional properties may be removed using a null value.

OpenAPI 2.0 does not allow to document the use of null values. Instead, a MergePatch marker type should be used, defined in common-v1.yaml.

Example 16. JSON merge patch

PATCH https://api.socialsecurity.be/demo/v1/employers/93017373 HTTP/1.1

PATCH

/employers/{employerId}

Performs a partial update of an existing employer.

Request

body

application/merge-patch+json or application/json

{
  "bankrupt": false,
  "bankruptDate": null
}

schema

OpenAPI 3.0

EmployerPatch:
  type: object
  properties:
    bankrupt:
      type: boolean  # mandatory property, shouldn't be nullable
    bankruptDate:
      type: string
      format: date
      nullable: true # optional property, use null to remove it

OpenAPI 2.0

# Schema from https://github.com/belgif/openapi-common/blob/master/src/main/swagger/common/v1/common-v1.yaml
MergePatch:
  description: JSON Merge Patch (RFC 7386) request body
  type: object
  additionalProperties: true
  # Marker type as JSON Merge Patch requests can not be fully specified as a JSON Schema type in OpenAPI 2.0

Parameters

employerId

path-param

employer ID of NSSO uniquely identifying the employer.

Response

body

empty or the complete resource after applying PATCH

{
    "employerId": 93017373,
    "name": "Belgacom",
    "bankrupt": false
}

Most used response codes

Success code with resource after applying PATCH returned.

No Content

Success code without returning the resource.

Bad request

The input data is not valid according the data schema.

Not Found

The resource does not exist and thus cannot be updated.

Conflict

The client data is in conflict with the data on the server e.g. optimistic locking issues.

4.3.4. Remove

Use DELETE when you like to delete a document resource.

Example 17. Deleting a document resource

DELETE https://api.socialsecurity.be/demo/v1/employers/93017373 HTTP/1.1

DELETE

/employers/{employerId}

Deletes an employer.

Parameters

employerId

path-param

employer ID of NSSO uniquely identifying the employer.

Response

body

empty or a message indicating success

204 No Content

or

200 OK
{
 "message": "Employer is deleted."
}

Most used response codes

Success code with the deleted resource returned.

No Content

Success code with the deleted resource not returned.

Bad request

Generic error on client side. For example, the syntax of the request is invalid.

Not Found

The resource does not exist and thus cannot be deleted.

Conflict

A constraint on the resource is violated. The resource could not be deleted because the request is in conflict with the current state of the resource.

For example, a REST API may return this response code when a client tries to DELETE a non-empty store resource.

4.3.5. Long-running tasks

Some operations need to be performed asynchronously, as they take too long to complete.

Rule: Long-running tasks [lng-task]

Long-running tasks MUST be represented as a resource. The task resource is created using a POST action returning a 202 Accepted response containing the URL of the task in the Location HTTP header. It can then be fetched by the client to get the processing status of the task.

When GETting the task resource, the response can be:

Still processing: status 200 OK and a representation of the task’s current status
Success: status 303 See Other with the Location header containing the URL of the task’s output.
Failure: status 200 OK with a representation of the task’s status, including the reason of the failure

Variations on the above may be required, e.g. if the task has no output, the response on success may be 200 OK without a Location header. The schema common-v1.yaml defines the representation of a task’s status.

Example 18. Long-running task

Submitting the task

POST /images/tasks

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Location: http://www.example.org/images/tasks/1
Date: Sun, 13 Sep 2018 01:49:27 GMT

{
  "self": "/images/tasks",
  "status": {
    "state": "processing",
    "pollAfter": "2018-09-13T01:59:27Z"
  }
}

The response 202 Accepted status indicates that the server accepted the request for processing. pollAfter hints when to check for an updated status at a later time.

Getting the processing status

GET /images/tasks/1

When the server is still processing the task

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "self": "/images/tasks/1",
  "status": {
    "state": "processing",
    "pollAfter": "2018-09-13T02:09:27Z"
  }
}

When processing has completed

HTTP/1.1 303 See Other
Location: http://www.example.org/images/1
Content-Type: application/json;charset=UTF-8

{
  "self": "/images/tasks/1",
  "status": {
    "state": "done",
    "completed":"2018-09-13T02:10:00Z"
  }
}

The Location header refers to the result of the task.

In case of failure during processing

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "self": "/images/tasks/1",
  "status": {
    "state": "failed",
    "completed":"2018-09-13T02:10:00Z",
    "problem": {
      "instance": "urn:uuid:d9e35127-e9b1-4201-a211-2b52e52508df",
      "title": "Bad Request",
      "status": 400,
      "type": "urn:problem-type:example:invalidImageFormat",
      "href": "https://example.org/example/v1/refData/problemTypes/urn:problem-type:example:invalidImageFormat",
      "detail": "Invalid image format"
    }
  }
}

Note that the status code is 200 OK as the retrieval of the task’s status succeeded. The cause of failure is represented using an embedded Problem object, as defined in Error handling.

4.4. Collection

A collection resource is a server-managed list of document resources.

Rule: Collection name [col-name]

A plural noun SHOULD be used for collection names, for example 'employers' or 'children'.

Example 19. Collection name

https://api.socialsecurity.be/demo/v1/employers - a collection of employers

https://api.socialsecurity.be/demo/v1/persons/{ssin}/children - a collection of children as a child resource of a person

4.4.1. Consult

Rule: Representation of a collection [col-repres]

The representation of a collection MUST contain a list of links to child resources:

A collection result MUST contain an items property with an array of objects, each one representing an item in the collection.
In these objects, a href property MUST be present with a link to the resource.
The unique business identifier SHOULD be present for each item.
Each item object MAY be extended with some key business properties, needed for display in a master view.
In case the collection is empty, the items property MUST have an empty array as value.
The title property MAY be used to provide a human-readable description for an item, usable as display text for the link.
The number of items in the collection result set MAY be included in the response using the total property. If the response is paginated, its value MUST correspond to the number of items regardless of pagination, rather than only the number of items in the current page.

A collection resource, like other resources, MUST always return a JSON object as top-level data structure to support extensibility ([evo-object]). Do not return a JSON array, because the moment you like to add paging, hypermedia links, etc. your API will break.

Table 1. Most used response codes
200	OK	Default response code, also when the collection is empty.
400	Bad Request	Generic error on client side. For example, the syntax of the request is invalid.
404	Not found	The URI provided cannot be mapped to a resource.

204 No content should not be used with GET.

Rule: Sorting a collection [col-sort]

A sort multi-value query parameter MAY be provided to allow a client to sort the items of a collection resource on one or more specified properties. Descending sorting order can be indicated by prefixing the property name with -.

The API SHOULD document which properties can be used for sorting, and whether descending order is allowed.

Table 2. Sort query parameter
sort	Multi-value query param with list of properties to sort on. Direction is ascending by default. To indicate descending, prefix property with `-`.	`?sort=age&sort=-name`

Example 20. Consulting a collection

GET https://api.socialsecurity.be/demo/v1/employers HTTP/1.1

Response

{
 "self": "https://api.socialsecurity.be/demo/v1/employers",
 "items":[
   {
     "href":"/employers/93017373",
     "title":"Belgacom",
     "employerId": 93017373,
     "enterpriseNumber": "0202239951"
   },
   {
     "href":"/employers/20620259",
     "title":"Partena VZW",
     "employerId": 20620259,
     "enterpriseNumber": "0409536968"
   }
 ],
 "total":2
}

JSON data types

EmployersCollection:
  allOf:
  - $ref: common/v1/common-v1.yaml#/components/schemas/SelfLink
  - type: object
    properties:
      items:
        type: array
        items:
          $ref: "#/components/schemas/EmployerLink"
      total:
        type: integer
    required:
      - items
      - total
EmployerLink:
  allOf:
  - $ref: common/v1/common-v1.yaml#/components/schemas/HttpLink
  - type: object
    properties:
      employerId:
        $ref: "./employer/identifier/v1/employer-identifier-v1beta.yaml#/components/schemas/EmployerId"
      enterpriseNumber:
        $ref: "./organization/identifier/v1/organization-identifier-v1.yaml#/components/schemas/EnterpriseNumber"

Rule: Getting full representations of collection items [col-embed]

When the collection items contain few data, you may want to retrieve them in full when getting the collection. In this case, the full representations MUST be included in an 'embedded' property as described in Embedding resources.

Example 21. Consulting a collection with embedded items

GET https://api.socialsecurity.be/demo/v1/appendices/employerclasses?embed=items HTTP/1.1

Response

{
 "self": "/appendices/employerclasses?embed=items",
 "items": [
  {
   "value": "0",
   "href": "/appendices/employerclasses/0"
  }, {
   "value": "2",
   "href": "/appendices/employerclasses/2"
  }
 ],
 "total":2,
 "embedded": {
   "/appendices/employerclasses/2": {
     "self": "/appendices/employerclasses/2",
     "value": "2",
     "description": {
       "nl": "Bijzondere categorie voor werkgevers die voor hun arbeiders een speciale bijdrage verschuldigd zijn.",
       "fr": "Catégorie particulière pour les employeurs redevables pour les ouvriers d’une cotisation spéciale."
      }
   },
   "/appendices/employerclasses/0": {
     "self": "/appendices/employerclasses/0",
     "value": "0",
     "description": {
      "nl": "Algemene categorie voor werkgevers van commerciële of niet-commerciële aard.",
      "fr": "Catégorie générale pour les employeurs, de type commercial ou non-commercial."
     }
   }
 }
}

JSON data types

AppendixCodesCollection:
  description: A collection of appendix codes
  type: object
  properties:
    items:
      type: array
      items:
        $ref: '#/components/schemas/AppendixCodeLink'
    total:
      type: integer
    embedded:
      type: object
      additionalProperties:
        $ref: 'appendixCode.yaml#/components/schemas/AppendixCode'
  required:
    - items
    - total
AppendixCodeLink:
  allOf:
  - $ref: 'common/v1/common-v1.yaml#/components/schemas/HttpLink'
  - type: object
    properties:
      value:
        $ref: 'appendixCode.yaml#/components/schemas/AppendixCodeValue'

4.4.2. Filtering

Rule: Filtering items in a collection [col-filter]

A collection may support query parameters to filter its items:

a query parameter with the name of a document property, filters items on the specified value
the query parameter q is reserved for a full text search on all the document’s content
other filter parameters may be supported, e.g. to look up items within a search period

Unless the API documentation explicitly states otherwise, returned collection items:

should satisfy ALL filter query parameters (AND-logic)
have to match ANY of the values of a multi-valued filter query parameter (OR-logic).

For example, the query GET /cars?doors=5&color=black&color=blue should be interpreted by default as: "search for all cars that have 5 doors AND are of color blue OR black".

GET

/employers

get all the employers documents in the collection

Parameters

name

query-param

Filter only employers that have a specific name.

Response

body

{
  "self": "/companies?name=belg",
        "items": [{
                "href": "/companies/202239951",
                "title": "Belgacom"
        }, {
                "href": "/companies/448826918",
                "title": "Carrefour Belgium SA"
        }],
        "total": 2
}

Most used response codes

Default response code, also when the filtered collection is empty.

Bad Request

Generic error on client side. For example, the syntax of the request is invalid.

Not found

The URI provided cannot be mapped to a resource.

204 No content should not be used with GET.

GET https://api.socialsecurity.be/demo/v1/companies?name=belg HTTP/1.1

4.4.3. Pagination

Rule: Paging over a large collection [col-paging]

Collection with too many items MUST support pagination. There are two pagination techniques:

offset-based pagination: numeric offset identifies a page
cursor-based (aka key-based or luke index): a unique key element identifies a page

Cursor-based pagination has some advantages, especially for high volumes. Take into account the considerations listed in the Zalando API guidelines before choosing a pagination technique.

Table 3. Reserved JSON properties:
`next`	MANDATORY (except for the last page)	hyperlink to the next page
`prev`	OPTIONAL	hyperlink to the previous page
`pageSize`	RECOMMENDED	Maximum number of items per page. For the last page, its value should be independent of the number of actually returned items.
`page`	MANDATORY (offset-based); N/A (cursor-based)	index of the current page of items, should be 1-based (the default and first page is 1)
`first`	OPTIONAL	hyperlink to the first page
`last`	OPTIONAL	hyperlink to the last page
`total`	OPTIONAL	Total number of items across all pages. If query parameters are used to filter the result set, this is the total of the collection result set, not of the entire collection.

The names of the properties with hyperlink values and the items property are derived from the IANA registered link relations.

Table 4. Reserved query parameters:
`pageSize`	OPTIONAL	maximum number of items per page desired by client; must have a default value if absent.
`page`	MANDATORY with default value 1 (offset-based); N/A (cursor-based)	the index of page to be retrieved

Example 22. Offset-based pagination

GET https://api.socialsecurity.be/demo/v1/companies?page=2&pageSize=2 HTTP/1.1

{
  "self": "/companies?page=2&pageSize=2",
  "items": [
    {
      "href": "/companies/202239951",
      "title": "Belgacom"
    },
    {
      "href": "/companies/212165526",
      "title": "CPAS de Silly"
    }
  ],
  "pageSize": 2,
  "page": 2,
  "total": 7,
  "first": "/companies?pageSize=2",
  "last": "/companies?page=4&pageSize=2",
  "prev": "/companies?page=1&pageSize=2",
  "next": "/companies?page=3&pageSize=2"
}

Example 23. Cursor-based pagination

GET https://api.socialsecurity.be/demo/v1/companies?afterCompany=0244640631 HTTP/1.1

{
  "self": "/companies?afterCompany=0244640631&pageSize=2",
  "items": [
    {
      "href": "/companies/202239951",
      "title": "Belgacom"
    },
    {
      "href": "/companies/212165526",
      "title": "CPAS de Silly"
    }
  ],
  "pageSize": 2,
  "total": 7,
  "first": "/companies?pageSize=2",
  "next": "/companies?afterCompany=0212165526&pageSize=2"
}

4.4.4. Create a new resource

The collection resource can be used to create new document resources from the POST request body. Absent optional values are set to their default value if one is specified in the OpenAPI specification.

/employers

create a new employer in the collection

Request

body

The data of the resource to create.

{
  "name": "Belgacom",
  "employerId": 93017373,
  "company": {
    "enterpriseNumber": "0202239951"
  }
}

Response headers

Location

http-header

The URI of the newly created resource e.g. /employers/93017373

Response

body

The API should specify for each creation operation, if it returns:

an empty body,
a partial resource representation (e.g. only a generated resource identifier),
or a full resource representation.

Most used response codes

201

Created

Default response code if the resource is created.

Conflict

The resource could not be created because the request is in conflict with the current state of the resource. E.g. the resource already exists (duplicate key violation).

303

See Other

The resource already exists. May be returned instead of 409 Conflict if it is considered a normal use case to perform the operation for an already existing resource. The Location header refers to the resource.

200 OK should not be used with POST for creating resources.

POST /employers HTTP/1.1

HTTP/1.1 201 Created
Location: /employers/93017373
Content-Length: 0
Date: Wed, 06 Jan 2016 15:37:16 GMT

4.4.5. Remove

A selection of items can be removed from a collection using the DELETE method. In fact, the collection itself cannot be removed, but it can be emptied if all its items are removed. By using query parameters, the items to be removed can be filtered. In order to remove a single specific item from a collection, use DELETE on the document resource.

DELETE

/employers

Delete all the employers documents in the collection.

Parameters

name

query-param

Remove only employers that have a specific name.

Response

body

Empty or a message incidating success.

Most used response codes

The items are successfully removed from the collection and returned.

No content

The items are successfully removed from the collection but no additional content is included in the response body.

Bad Request

Generic error on client side. For example, the syntax of the request is invalid.

idempotent actions without side effects

Not found

The collection resource does not exist and thus cannot be deleted.

4.5. Controller

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

A REST API can rely on controller resources to perform application-specific actions that cannot be logically mapped to one of the standard methods (standard CRUD-operations).

Rule: Controller resource [ctl-res]

A controller resource name is a verb instead of a noun.

The HTTP method on a controller SHOULD be:

POST for actions with side effects (state change) or actions without side effects but requiring a request body
GET for idempotent actions without side effects

Example 24. Controller examples

Withdrawal from an account:

POST /accounts/123/withdraw

Sending a notification to an employer:

POST /employers/93017373/sendNotification

Converting money from one currency to another (using GET because of no side effects):

GET /convertMoney?from=EUR&amount=45&to=USD

4.5.1. Controller vs document

Rule: Reification of controller resource [ctl-reific]

Before using a controller resource to represent an action, consider reifying the action as a collection or document resource (noun) describing the intent of the action.

Long-running tasks are an example of actions modelled as a collection/document instead of a controller.

Example 25. Reification examples

Withdrawal from an account as a controller resource:

POST /account/123/withdraw

or as a collection resource:

POST /account/123/withdrawals

Using a noun improves extensibility in this case. For instance, a GET operation could be added to consult a history of all withdrawals executed on the account.

5. HTTP Methods

5.1. GET

GET must be used to retrieve a representation of a resource. It is a strict read-only method, which should never modify the state of the resource.

5.2. POST

POST must be used to create a new resource in a collection or to execute a controller resource.

When using for resource creation, the POST request’s body contains the suggested state representation of the new resource to be added to the server-owned collection. The response should contain a Location HTTP header containing the URI of the newly created resource, while the body contains either its (partial or full) representation or is empty.

POST operations may have side effects (i.e. modify state), and are not required to be idempotent.

5.3. PUT

PUT must be used to update a stored resource under a consumer supplied URI. It could be used to insert a new resource in case the client application decides on the resource identifier.

If the URI refers to an already existing resource, the enclosed entity SHOULD be considered as a new version to replace the one residing on the server. If the target resource is successfully modified in accordance with the state of the enclosed representation, then a 200 (OK) response SHOULD be sent to indicate successful completion of the request.

If the URI does not point to an existing resource, and that URI is capable of being defined as a new resource, the server can create the resource with that URI. The server MUST inform the client by sending a 201 (Created) response to indicate succesful creation.

PUT operations may have side effects (i.e. modify state), but MUST be idempotent.

5.4. PATCH

PATCH must be used to update partially a representation of a resource.

The enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH. PATCH operations are not required to be idempotent, however they will often be in pratice.

See Partial update on how to specify the set of instructions describing how a resource on the server should be modified.

Compatibility

The PATCH http method may not be supported in all components participating in the communication (e.g. HTTP client, intermediary proxy). If these can’t be upgraded to add support, client and server may agree to work around this by implementing PATCH as POST operations with HTTP header 'X-HTTP-Method-Override: PATCH'.

5.5. DELETE

DELETE must be used to remove a resource from its parent. Once a DELETE request has been processed for a given resource, the resource can no longer be found by clients. Therefore, any future attempt to retrieve the resource’s state representation, using either GET or HEAD, must result in a 404 (“Not Found”) status returned by the API.

5.6. HEAD

HEAD should be used to only retrieve the HTTP response headers. HEAD returns the same response as GET, except that the API returns an empty body. It is strictly read-only.

5.7. OPTIONS

OPTIONS should be used to retrieve metadata that describes a resource’s available interactions.

5.8. How to use each method

Rule: Use appropriate HTTP method [meth-http]

The HTTP methods SHOULD be used that are appropriate for the type of action performed on the resource.

The table below lists the usages of HTTP methods for each resource archetype. Combinations explicitly excluded ( -) SHOULD NOT be used.

Method	Document	Collection	Controller	Request body	Response body
GET	consult	consult	idempotent actions without side effects	Empty	Resource(s)
POST	-	create document	action with side effects or requiring request body	Representation of the created resource or controller info	Optional
PUT	full update	-	-	Representation of the updated resource	Optional
PATCH	partial update	-	-	Fields of the resource to update	Optional
DELETE	remove	remove selection of items	-	Empty	Optional
HEAD	X	X	X	Empty	Empty
OPTIONS	X	X	X	Empty	Optional

Method

Document

Collection

Controller

Request body

Response body

GET

consult

Empty

Resource(s)

action with side effects or requiring request body

create document

Representation of the created resource or controller info

Optional

PUT

full update

Representation of the updated resource

Optional

PATCH

partial update

Fields of the resource to update

Optional

DELETE

remove

remove selection of items

Empty

Optional

HEAD

Empty

OPTIONS

Empty

Optional

6. Status codes

6.1. Overview

Rule: Use appropriate HTTP status codes [stat-codes]

The HTTP response status code SHOULD be returned that best describes the outcome of the treatment of the request.

The table below list most common combinations of a status code for each HTTP method, though may not be exhaustive. Combinations explicitly excluded ( -) SHOULD NOT be used.

The full list of HTTP status codes is documented here.

This HTTP status codes chart (takes a while to load) shows a decision tree to determine the usage of the correct HTTP status code.

Code	GET	HEAD	PUT	POST	PATCH	DELETE	OPTIONS
200 OK	X	X	X	X (controller only)	X	X	X
201 Created	-	-	X (creation only)	X	-	-	-
202 Accepted	-	-	-	X	-	-	X
204 No Content	-	X	X	X	X	X	-
301 Moved Permanently	X	X	X	X	X	X	X
303 See Other	X	X	X	X	X	X	X
304 Not Modified	X	X	-	-	-	-	-
307 Temporary Redirect	X	X	X	X	X	X	X
400 Bad Request	X	X	X	X	X	X	X
401 Unauthorized	X	X	X	X	X	X	X
403 Forbidden	X	X	X	X	X	X	X
404 Not Found	X	X	X	X	X	X	X
405 Method Not Allowed	X	X	X	X	X	X	-
406 Not Acceptable	X	X	X	X	X	X	X
409 Conflict	-	-	X	X	X	X	-
412 Precondition Failed	-	-	X	X	X	X	-
413 Payload Too Large	-	-	X	X	X	-	-
415 Unsupported Media Type	X	X	X	X	X	X	X
429 Too Many Requests	X	X	X	X	X	X	X
500 Internal Server Error	X	X	X	X	X	X	X
502 Bad Gateway	X	X	X	X	X	X	X
503 Service Unavailable	X	X	X	X	X	X	X

Code

GET

HEAD

PUT

POST

PATCH

DELETE

OPTIONS

X (controller only)

X (creation only)

301 Moved Permanently

303 See Other

304 Not Modified

307 Temporary Redirect

405 Method Not Allowed

406 Not Acceptable

409 Conflict

412 Precondition Failed

413 Payload Too Large

415 Unsupported Media Type

429 Too Many Requests

500 Internal Server Error

502 Bad Gateway

503 Service Unavailable

6.2. List of status codes

6.2.1. 1xx Informational

Request received, continuing process.

6.2.2. 2xx Success

The action was successfully received, understood, and accepted.

Code	Description	Methods
200 OK	200 (“OK”) should be used to indicate nonspecific success In most cases, 200 is the code the client hopes to see. It indicates that the REST API successfully carried out whatever action the client requested, and that no more specific code in the 2xx series is appropriate. Unlike the 204 status code, a 200 response should include a response body.	GET, HEAD, PUT, PATCH, DELETE, OPTIONS
201 Created	201 (“Created”) must be used to indicate successful resource creation A REST API responds with the 201 status code whenever a collection creates, or a store adds, a new resource at the client’s request. The response body may be empty or contain a partial or full representation of the new resource. There may also be times when a new resource is created as a result of some custom POST action, in which case 201 would also be an appropriate response.	POST PUT only in case it is used to create a new document resource.
202 Accepted	202 (“Accepted”) must be used to indicate successful start of an asynchronous action A 202 response indicates that the client’s request will be handled asynchronously. This response status code tells the client that the request appears valid, but it still may have problems once it’s finally processed. A 202 response is typically used for actions that take a long while to process (see Long-running tasks). A POST method may send 202 responses, but other methods should not.	POST
204 No Content	204 (“No Content”) should be used when the response body is intentionally empty The 204 status code is usually sent out in response to a PUT, POST, PATCH or DELETE request, when the REST API declines to send back any status message or representation in the response message’s body.	POST, HEAD, PUT, PATCH, DELETE, OPTIONS

Code

Description

Methods

200 OK

200 (“OK”) should be used to indicate nonspecific success

In most cases, 200 is the code the client hopes to see. It indicates that the REST API successfully carried out whatever action the client requested, and that no more specific code in the 2xx series is appropriate. Unlike the 204 status code, a 200 response should include a response body.

GET, HEAD, PUT, PATCH, DELETE, OPTIONS

201 Created

201 (“Created”) must be used to indicate successful resource creation

A REST API responds with the 201 status code whenever a collection creates, or a store adds, a new resource at the client’s request. The response body may be empty or contain a partial or full representation of the new resource. There may also be times when a new resource is created as a result of some custom POST action, in which case 201 would also be an appropriate response.

PUT only in case it is used to create a new document resource.

202 Accepted

202 (“Accepted”) must be used to indicate successful start of an asynchronous action

A 202 response indicates that the client’s request will be handled asynchronously. This response status code tells the client that the request appears valid, but it still may have problems once it’s finally processed. A 202 response is typically used for actions that take a long while to process (see Long-running tasks). A POST method may send 202 responses, but other methods should not.

GET http://myrestapi/family/32456?embed=children&embed=parents

204 No Content

204 (“No Content”) should be used when the response body is intentionally empty

The 204 status code is usually sent out in response to a PUT, POST, PATCH or DELETE request, when the REST API declines to send back any status message or representation in the response message’s body.

POST, HEAD, PUT, PATCH, DELETE, OPTIONS

6.2.3. 3xx Redirection

Further action must be taken in order to complete the request.

Code Description Methods

Code	Description	Methods
301 Moved Permanently	301 (“Moved Permanently”) should be used to relocate resources The 301 status code indicates that the REST API’s resource model has been significantly redesigned and a new permanent URI has been assigned to the client’s requested resource. The REST API should specify the new URI in the response’s Location header.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
303 See Other	303 (“See Other”) should be used to refer the client to a different URI The 303 status code allows a REST API to send a reference to a resource without forcing the client to download its state. Instead, the client may send a GET request to the value of the Location header. It can be used when a long-running action has finished its work, but instead of sending a potentially unwanted response body, it sends the client the URI of a response resource. This can be the URI of a temporary status message, or the URI to some already existing, more permanent, resource.	All methods are acceptable. Mostly used with POST.
304 Not Modified	304 (“Not Modified”) should be used to preserve bandwidth This status code is similar to 204 (“No Content”) in that the response body must be empty. The key distinction is that 204 is used when there is nothing to send in the body, whereas 304 is used when there is state information associated with a resource but the client already has the most recent version of the representation. This status code is used in conjunction with conditional HTTP requests.	GET, HEAD
307 Temporary Redirect	307 (“Temporary Redirect”) should be used to tell clients to resubmit the request to another URI A 307 response indicates that the REST API is not going to process the client’s request. Instead, the client should resubmit the request to the URI specified by the response message’s Location header. A REST API can use this status code to assign a temporary URI to the client’s requested resource. For example, a `307` response can be used to shift a client request over to another host.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

301 Moved Permanently

301 (“Moved Permanently”) should be used to relocate resources

The 301 status code indicates that the REST API’s resource model has been significantly redesigned and a new permanent URI has been assigned to the client’s requested resource. The REST API should specify the new URI in the response’s Location header.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

303 See Other

303 (“See Other”) should be used to refer the client to a different URI

The 303 status code allows a REST API to send a reference to a resource without forcing the client to download its state. Instead, the client may send a GET request to the value of the Location header.

It can be used when a long-running action has finished its work, but instead of sending a potentially unwanted response body, it sends the client the URI of a response resource. This can be the URI of a temporary status message, or the URI to some already existing, more permanent, resource.

All methods are acceptable.

Mostly used with POST.

304 Not Modified

304 (“Not Modified”) should be used to preserve bandwidth

This status code is similar to 204 (“No Content”) in that the response body must be empty. The key distinction is that 204 is used when there is nothing to send in the body, whereas 304 is used when there is state information associated with a resource but the client already has the most recent version of the representation. This status code is used in conjunction with conditional HTTP requests.

GET, HEAD

307 Temporary Redirect

307 (“Temporary Redirect”) should be used to tell clients to resubmit the request to another URI

A 307 response indicates that the REST API is not going to process the client’s request. Instead, the client should resubmit the request to the URI specified by the response message’s Location header.

A REST API can use this status code to assign a temporary URI to the client’s requested resource. For example, a 307 response can be used to shift a client request over to another host.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

6.2.4. 4xx Client Error

The request contains bad syntax or cannot be fulfilled.

Code Description Method

Code	Description	Method
400 Bad Request	400 (“Bad Request”) may be used to indicate nonspecific failure 400 is the generic client-side error status, used when no other 4xx error code is appropriate.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
401 Unauthorized	401 (“Unauthorized”) must be used when there is a problem with the client’s credentials. A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
403 Forbidden	403 (“Forbidden”) should be used to forbid access regardless of authorization state. A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it. A 403 response is not a case of insufficient client credentials; that would be `401 (“Unauthorized”)`.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
404 Not Found	404 (“Not Found”) must be used when a client’s URI cannot be mapped to a resource. The 404 error status code indicates that the REST API can’t map the client’s URI to a resource.	All: GET, HEAD, PUT, PATCH, DELETE, OPTIONS, POST (if parent resource not found)
405 Method Not Allowed	405 (“Method Not Allowed”) must be used when the HTTP method is not supported. The API responds with a 405 error to indicate that the client tried to use an HTTP method that the resource does not allow. For example, when a PUT or POST action is performed on a read-only resource supporting only GET and HEAD. A 405 response must include the Allow header, which lists the HTTP methods that the resource supports. For example: `Allow: GET, POST`	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
406 Not Acceptable	406 (“Not Acceptable”) must be used when the requested media type cannot be served The 406 error response indicates that the API is not able to generate any of the client’s preferred media types, as indicated by the `Accept` request header. For example, a client request for data formatted as `application/xml` will receive a 406 response if the API is only willing to format data as `application/json`.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
409 Conflict	409 (“Conflict”) should be used when a request conflicts with the current state of the target resource The 409 error response tells the client that they tried to put the REST API’s resources into an impossible or inconsistent state. For example, a REST API may return this response code when a client tries to DELETE a non-empty store resource.	POST, PUT, PATCH, DELETE
412 Precondition Failed	412 (“Precondition Failed”) should be used to support conditional operations The 412 error response indicates that the client specified one or more preconditions in its request headers, effectively telling the REST API to carry out its request only if certain conditions were met. A 412 response indicates that those conditions were not met, so instead of carrying out the request, the API sends this status code. Only use for conditional HTTP requests, not constraints expressed in the HTTP payload. Use `409 Conflict` instead.	POST, PUT, PATCH, DELETE
413 Payload Too Large	413 (“Payload Too Large”) should be used when a request is refused because its payload is too large The 413 error response indicates that the request is larger than the server is willing or able to process.	POST, PUT, PATCH
415 Unsupported Media Type	415 (“Unsupported Media Type”) must be used when the media type of a request’s payload cannot be processed The 415 error response indicates that the API is not able to process the client’s supplied media type, as indicated by the `Content-Type` request header. For example, a client request including data formatted as `application/xml` will receive a 415 response if the API is only willing to process data formatted as application/json.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
429 Too Many Requests	429 (“Too Many Requests”) should be used to indicate that the user has sent too many requests in a given amount of time. The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request. Note that this specification does not define how the origin server identifies the user, nor how it counts requests. Responses with the 429 status code MUST NOT be stored by a cache.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

400 Bad Request

400 (“Bad Request”) may be used to indicate nonspecific failure 400 is the generic client-side error status, used when no other 4xx error code is appropriate.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

401 Unauthorized

401 (“Unauthorized”) must be used when there is a problem with the client’s credentials.

A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

403 Forbidden

403 (“Forbidden”) should be used to forbid access regardless of authorization state.

A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it. A 403 response is not a case of insufficient client credentials; that would be 401 (“Unauthorized”).

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

404 Not Found

404 (“Not Found”) must be used when a client’s URI cannot be mapped to a resource.

The 404 error status code indicates that the REST API can’t map the client’s URI to a resource.

All: GET, HEAD, PUT, PATCH, DELETE, OPTIONS, POST (if parent resource not found)

405 Method Not Allowed

405 (“Method Not Allowed”) must be used when the HTTP method is not supported.

The API responds with a 405 error to indicate that the client tried to use an HTTP method that the resource does not allow. For example, when a PUT or POST action is performed on a read-only resource supporting only GET and HEAD.

A 405 response must include the Allow header, which lists the HTTP methods that the resource supports. For example: Allow: GET, POST

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

406 Not Acceptable

406 (“Not Acceptable”) must be used when the requested media type cannot be served

The 406 error response indicates that the API is not able to generate any of the client’s preferred media types, as indicated by the Accept request header. For example, a client request for data formatted as application/xml will receive a 406 response if the API is only willing to format data as application/json.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

409 Conflict

409 (“Conflict”) should be used when a request conflicts with the current state of the target resource

The 409 error response tells the client that they tried to put the REST API’s resources into an impossible or inconsistent state. For example, a REST API may return this response code when a client tries to DELETE a non-empty store resource.

POST, PUT, PATCH, DELETE

412 Precondition Failed

412 (“Precondition Failed”) should be used to support conditional operations

The 412 error response indicates that the client specified one or more preconditions in its request headers, effectively telling the REST API to carry out its request only if certain conditions were met. A 412 response indicates that those conditions were not met, so instead of carrying out the request, the API sends this status code.

Only use for conditional HTTP requests, not constraints expressed in the HTTP payload. Use 409 Conflict instead.

POST, PUT, PATCH, DELETE

413 Payload Too Large

413 (“Payload Too Large”) should be used when a request is refused because its payload is too large

The 413 error response indicates that the request is larger than the server is willing or able to process.

POST, PUT, PATCH

415 Unsupported Media Type

415 (“Unsupported Media Type”) must be used when the media type of a request’s payload cannot be processed

The 415 error response indicates that the API is not able to process the client’s supplied media type, as indicated by the Content-Type request header. For example, a client request including data formatted as application/xml will receive a 415 response if the API is only willing to process data formatted as application/json.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

429 Too Many Requests

429 (“Too Many Requests”) should be used to indicate that the user has sent too many requests in a given amount of time.

The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request. Note that this specification does not define how the origin server identifies the user, nor how it counts requests.

Responses with the 429 status code MUST NOT be stored by a cache.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

6.2.5. 5xx Server Error

The server failed to fulfill an apparently valid request.

Code	Description	Methods
500 Internal Server Error	500 (“Internal Server Error”) should be used to indicate API malfunction 500 is the generic REST API error response. Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception. A 500 error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response, and hope to GET a different response.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
502 Bad Gateway	The 502 ("Bad Gateway") status code indicates that the server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
503 Service Unavailable	503 (“Service Unavailable”) indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. The server MAY send a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

Code

Description

Methods

500 Internal Server Error

500 (“Internal Server Error”) should be used to indicate API malfunction

500 is the generic REST API error response. Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception.

A 500 error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response, and hope to GET a different response.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

502 Bad Gateway

The 502 ("Bad Gateway") status code indicates that the server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

503 Service Unavailable

503 (“Service Unavailable”) indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

The server MAY send a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

7. Media Types

The HTTP protocol supports content negotiation for media types of the response.

Rule: Content negotiation [cnt-negot]

REST clients SHOULD specify the media type(s) that is(/are) acceptable for the response in the Accept HTTP header.

A REST response or request with payload MUST include the Content-Type HTTP header to indicate the media type of the HTTP payload.

Status code 406 MUST be used to indicate that the requested media type could not be provided.

Status code 415 MUST be used to indicate an unsupported media type in the request payload.

If a resource supports multiple content types through negotation, the response header Vary: Accept MUST be added to avoid undesired cache hits (also see Caching).

Example 26. Content negotiation

Request HTTP headers:

Accept: image/jpeg, image/png

Response HTTP headers:

Content-Type: image/png
Vary: Accept

JSON

The primary media type to support is JSON (Javascript Object Notation). The choice for JSON is particularly made for supporting JavaScript clients.

Rule: Representation of structured data [rep-struct]

Structured data MUST be made available in JSON format (RFC 8259) with media type application/json. JSON text MUST be encoded using UTF-8.

Some legacy clients erroneously decode JSON payloads using a non-UTF-8 encoding by default. To work around this, a charset parameter may be added to the Content-Type HTTP header, even though it has no meaning according to the JSON RFC.

Content-Type: application/json;charset=UTF-8

Media types of format application/<subtype>+json may be used for standardized JSON formats, though REST APIs should also accept requests using the generic application/json media type:

application/merge-patch+json for JSON Merge Patch payloads (see Partial update)
application/problem+json for Problem Detail for HTTP APIs (RFC 9457) payloads (see Error handling)

XML

On specific client request, a REST service can expose XML messages defined by XML Schema.

Content-Type: application/xml;charset=UTF-8

Always stick to UTF-8 encoding and specify the charset in the Content-Type HTTP header.

It is not recommended to implement both JSON / XML in each REST service. It would require to define and implement two representations of the same data. Automatic conversion between the two standards will almost never give a satisfying result.

Media types in OpenAPI

Payload media types can be specified in an OpenAPI specification.

For JSON, the media type specified in OpenAPI should not contain a charset parameter, because this is known to lead to problems in some server software when treating requests without the parameter in the Accept header.

OpenAPI 3.0

OpenAPI 3.0 allows to specify a different media type for each request or response format. Default media types cannot be specified.

Example 27. Specifying OpenAPI 3.0 media types

  /persons/{ssin}/photo:
    get:
      summary: Get the photo of the person
      operationId: getPhoto
      parameters:
      - $ref: "person/identifier/v1/person-identifier-v1.yaml#/components/parameters/SsinQueryParameter"
      responses:
        "200":
          description: successful operation
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          description: SSIN has invalid structure
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/InvalidSsinProblem"
        "404":
          description: SSIN was not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/UnknownSsinProblem"
        default:
          "$ref": "./problem/v1/problem-v1.yaml#/components/responses/ProblemResponse"

OpenAPI 2.0

The request and response body’s media type are specified in an OpenAPI 2.0 specification respectively by the consumes and produces keywords:

at operation level
at root level, as default media types for the entire specification

Example 28. Specifying media types at operation level

  /persons/{ssin}/photo:
    get:
      summary: Get the photo of the person
      operationId: getPhoto
      produces:
      - image/jpeg  # for photo
      - application/problem+json # for problems
      parameters:
      - $ref: "person/identifier/v1/person-identifier-v1.yaml#/parameters/SsinQueryParameter"
      responses:
        "200":
          description: successful operation
          schema:
            type: file
        "400":
          $ref: "#/responses/InvalidSsinResponse"
        "404":
          $ref: "#/responses/UnknownSsinResponse"

OpenAPI 2.0 doesn’t support specifying a different media type per status code.

Rule: Default media types [med-types]

OpenAPI 2.0 specifications SHOULD specify following default media types:

consumes:
- application/json

produces:
- application/json
- application/problem+json

8. Performance

8.1. Embedding resources

In order to reduce the number of requests, optional embedding of subresources may be used.

Rule: Embedding subresources [prf-embed]

Embedded subresources MUST be put in a JSON object named embedded at root level of the JSON document. In this object, each property key is the URI and the value the full JSON representation of the subresource. The URI MUST be the same as the href value by which the subresource is referenced in the representation of the main resource.

Embedded resources are returned at the client’s request if the embed query parameter is specified. The name of the JSON property referencing the subresource can be used as value of the embed parameter.

This way of embedding resources limits the changes required when a clients starts to use it, and only impacts the JSON Schema type of the root document. It also works well when there are multiple occurrences of the same subresource, and when embedding resources more than one level deep.

In JSON Schema, additionalProperties can be used to specify the data types allowed in embedded. Note that it not possible to specify more than one data type this way in OpenAPI, so the only restriction that can be specified is type: object when there are multiple embedded data types.

Example 29. Embedding subresources

{
  "self": "http://myrestapi/family/32456",
  "family": {
    "parents": [{
      "ssin": "12345678901",
      "href": "http://myrestapi/people/12345678901"
    }],
    "children": [{
      "ssin": "98765432101",
      "href": "http://myrestapi/people/98765432101"
    }]
  },
  "embedded": {
    "http://myrestapi/people/12345678901": {
      "self": "http://myrestapi/people/12345678901",
      "ssin": "12345678901",
      "givenName": "Jane",
      "lastName": "Doe"
    },
    "http://myrestapi/people/98765432101": {
      "self": "http://myrestapi/people/98765432101",
      "ssin": "98765432101",
      "givenName": "Bobby",
      "lastName": "Doe"
    }
  }
}

JSON data type

Family:
  description: A family
  type: object
  properties:
    parents:
      type: array
      items:
        $ref: '#/components/schemas/PersonRef'
    children:
      type: array
      items:
        $ref: '#/components/schemas/PersonRef'
    embedded:
      type: object
      additionalProperties:
        $ref: 'person.yaml#/components/schemas/Person'

Example 30. Query parameters for subresources more than one level deep

GET https://api.socialsecurity.be/demo/v1/employer/409536968?embed=employees(address)

8.2. Caching

Rule: HTTP Caching [prf-cach]

HTTP caching SHOULD be considered for resource types for which the same resources are repeatedly retrieved by clients.

The following schema shows a decision tree for the caching setup for a given resource:

8.2.1. Conditional requests

Conditional requests are those where the client can ask the server if it has an updated copy of the resource. The client will send some information about the cached resource it holds and the server will determine whether updated content should be returned or the client’s copy is already up to date. In the latter case, an HTTP status of 304 Not Modified is returned.

Though conditional requests do invoke a call across the network, unmodified resources result in an empty response body – saving the cost of transferring the resource back to the end client. The backend service is also often able to very quickly determine a resource’s last version or modification date without accessing the resource which itself saves non-trivial processing time.

Time-based

A time-based conditional request is based on the the last modified time of the resource. If the cached copy’s last modification time is still the most recent one, the server returns the 304 response code. To enable time-based conditional requests, the application specifies the last modified time of a resource via the Last-Modified response header.

Last-Modified: Mon, 03 Jan 2011 17:45:57 GMT

The next time the browser requests this resource it will only ask for the contents of the resource if they’re unchanged since this date using the If-Modified-Since request header

If-Modified-Since: Mon, 03 Jan 2011 17:45:57 GMT

If the resource hasn’t changed since Mon, 03 Jan 2011 17:45:57 GMT the server will return with an empty body with the 304 response code.

Rule: Precision of Last-Modified header [prf-lstmod]

The Last-Modified header doesn’t allow subsecond precision, which may lead to incorrect cache hits if there are two updates within a second.

Because of this, the ETag SHOULD be preferred over the Last-Modified header.

Content-based

The ETag (or Entity Tag) works in a similar way as the Last-Modified header except its value is a free-form tag identifying a resource version. Valid ETags can be a MD5 hash, a version number or a modification timestamp, allowing more precision than when using a Last-Modified-header.

This allows the server to identify if the cached contents of the resource are different to the most recent version.

ETag: "15f0fff99ed5aae4edffdd6496d7131f"

On subsequent browser requests, the If-None-Match request header is sent with the ETag value of the last requested version of the resource.

If-None-Match: "15f0fff99ed5aae4edffdd6496d7131f"

As with the If-Modified-Since header, if the current version has the same ETag value as the browser’s cached copy, then an HTTP status of 304 is returned.

8.2.2. Client caching directives

Cache-Control header

An HTTP client cache may cache server responses and decide to not even contact the server when the resource is requested again, saving the round trip to the server. The Cache-Control response header specifies directives for the client under which conditions and how long it should cache the response contents. This is useful for resources which don’t change frequently, and a client doesn’t need to be always synchronized with the latest version of the resource.

Example 31. Cache-Control response header

Cache-Control:public, max-age=86400

The response data may be cached by clients and intermediary servers as it is public, and should expire from the cache after 1 day (86400 seconds).

Vary header

The Vary response header describes which request headers, aside from the method, Host header field, and request target, influence the origin server’s process for selecting and representing this response. It is used to prevent unwanted cache hits.

See Best Practices for Using the Vary Header for more guidelines on the usage of the Vary header.

Example 32. Vary response header

Vary: Accept

This avoids using a cached XML response when a second request asks for JSON.

Never use Vary: * as it will result in a cache hit of 0.

References

Increasing Application Performance with HTTP Cache Headers
Google HTTP Caching
Best Practices for Using the Vary Header

9. JSON

All RESTful services must support JSON (Javascript Object Notation RFC 7159).

For extensibility, the payload (if any) of a RESTful request or response should always be a JSON object instead of an array, string, number, etc ([evo-object]). This way the request or response can always be extended with new properties ( [evo-compat]).

Rule: Naming of JSON properties [jsn-naming]

Following guidelines SHOULD be respected when determining a name for a JSON property:

use lowerCamelCase notation
- also for abbreviations: all letters after the first should be lowercase
use American English
do not use underscores (_), hyphens (-) or dots (.) in a property name, nor use a digit as first letter
don’t use overly generic terms like info(rmation) and data as property name or as part of it
the name should refer to the business meaning of its value in relation to the object in which it is specified, rather than how it is defined
omit parts of the name that are already clear from the context

Properties used from other standards, like OpenID Connect and OAuth2, are allowed to deviate from this rule.

KO OK

KO	OK
SSIN	ssin
street_RRN	streetRrn
customerInformation	customer
descriptionStringLength140	description
`"country": { "countryNisCode": 150, "countryIsoCode": "BE", "countryName": "Belgium" }`	`"country": { "nisCode": 150, "isoCode": "BE", "name": "Belgium" }`

SSIN

ssin

street_RRN

streetRrn

customerInformation

customer

descriptionStringLength140

description

"country": {
  "countryNisCode": 150,
  "countryIsoCode": "BE",
  "countryName": "Belgium"
}

"country": {
  "nisCode": 150,
  "isoCode": "BE",
  "name": "Belgium"
}

In below example, enterpriseNumber should be used even though the enterprise prefix is clear by its context. This is because enterpriseNumber is a fixed denomination (declared in Crossroads Bank for Enterprises) and using just number would rather cause confusion to type of identifier being used.

{
  "name": "Proximus",
  "employerId": 93017373,
  "enterprise": {
    "enterpriseNumber": "0202239951"
    "href": "/organizations/0202239951"
  }
}

Rule: Null values [jsn-null]

Properties without a value SHOULD be stripped from the JSON message, instead of having a null value.

For properties or parameters with a specified type, OpenAPI disallows null values by default, unless nullable: true is specified.

A notable exception to this rule are JSON Merge Patch requests, in which a null value indicates the removal of a JSON property.

Note that this rule doesn’t apply to empty values (e.g. empty strings "" or empty arrays []) as they are considered different from a null value.

NOK

{
  "name": "Proximus",
  "employerId": 93017373,
  "enterprise": null
}

{
  "name": "Proximus",
  "employerId": 93017373
}

The JSON properties have no specific order inside a JSON object.

{
  "name": "Proximus",
  "employerId": 93017373
}

{
  "employerId": 93017373,
  "name": "Proximus"
}

Dates are written in ISO 8601 full-date format: yyyy-MM-dd

Dates don’t include time zone or offset information. See OpenAPI 3.0 data types and RFC 3339 section 5.6.

{
  "birthday": "1930-07-19"
}

Schema with date

type: object
properties:
  birthDay:
    type: string
    format: date

Date/time are written in ISO 8601 date-time format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX

See JSON Schema Validation 7.3.1. date-time and RFC 3339 section 5.6. The fraction part .SSS for sub-second precision is optional and may be of any length. The time offset relative to UTC (XXX) is mandatory and may be Z (Zulu = offset 00:00) or of format ("+" / "-") time-hour ":" time-minute.

Example UTC

{
  "lastModification": "2016-04-24T09:26:01.5214Z"
}

Example with numeric offset

{
  "lastModification": "2016-04-24T11:26:00+02:00"
}

Schema with date-time

type: object
properties:
  lastModification:
    type: string
    format: date-time

10. API specifications

Rule: API contract-first approach [ctr-first]

The contract-first principle SHOULD be followed when developing an API. In this approach, the specifications of the REST API are created first and not generated from the code.

A code-first approach may sometimes be necessary however, as current state of technology does not always fully support contract-first development. In this case, special attention should be given that the API specifications remain stable and loosely coupled to the API implementation technology.

10.1. OpenAPI (Swagger)

OpenAPI is the dominating standard for API documentation, having gained wide industry support. It is based on Swagger, which has been standardized as OpenAPI 2.0.

Rule: OpenAPI [oas-contra]

Specifications of the API SHOULD be provided using OpenAPI 2.0 (aka Swagger) or OpenAPI 3.0. OpenAPI uses the OpenAPI Schema Object to describe the JSON representation of resources, which is a variant of JSON Schema, with some significant incompatibilities.

OpenAPI 3.1 improves upon OpenAPI 3.0, but to avoid interoperability problems it SHOULD NOT be used yet because it is not yet widely supported by most tooling.

The OpenAPI standard also includes a list of supported primitive data types.

You can visualize OpenAPI files using some of the tools listed in Tools.

Rule: Additional documentation [ext-docs]

Any additional documentation SHOULD be linked from the API’s OpenAPI definition using the externalDocs property.

Rule: Use YAML format for OpenAPI [oas-yaml]

OpenAPI files SHOULD be made available in YAML format, and OPTIONALLY in JSON format as well.

YAML is a superset of JSON which allows a simpler notation, and also allows comments. According to usage, a conversion step to JSON might be necessary considering limitations of tools.

Rule: Use tags to group operations [oas-tags]

When an API has many operations, tags SHOULD be used to group them together.

An operation SHOULD NOT have more than one tag.

Each tag used on an operation SHOULD also be declared in the top level tags list of the OpenAPI document, with an optional description.

The name of a tag SHOULD be stylized like a title, i.e. a word or space-separated word group starting with a capital letter.

Using tags will make the visual representation (e.g. SwaggerUI) more readable. Multiple tags on an operation duplicates the operation in SwaggerUI, which may cause confusion.

Declaring each tag allows linting tooling to detect inconsistencies in tag names.

Example 33. Using tags

tags:
  - name: Employers
    description: Managing employers
  - name: Reference data
paths:
  /employers/{employerId}:
    get:
      summary: Get an employer by its identifier
      tags:
        - Employers
  /employers:
    get:
      summary: Find employers matching given search parameters
      tags:
        - Employers
    post:
      summary: Add a new employer
      tags:
        - Employers
  /refData/employerClasses:
    get:
      summary: Find enterprises matching given search parameters
      tags:
        - referenceData # BAD: doesn't match declared tag name, words aren't separated by space, doesn't start with capital letter
        - Employers # BAD: don't set multiple tags on an operation

Rule: operationId [openapi-opid]

A unique operationId MUST be specified on each operation. It SHOULD have a lowerCamelCase value following common programming naming conventions for method (function) names.

Tools and libraries often use the operationId to uniquely identify an operation. Code generators use it to generate method names and generally take care of transforming it to the language-specific naming conventions (e.g. UpperCamelCase or snake_case).

Example 34. operationId

/health:
  get:
    summary: Check health of the service
    operationId: checkHealth   # Bad values: health, CheckHealth, healthCheck

Rule: General HTTP headers [gen-header]

HTTP header parameters that may be present on all or most operations of an API SHOULD NOT be documented explicitly in the OpenAPI specification, as this would clutter the spec and make it difficult to keep up to date. Rather, refer API users to general documentation on these headers.

Operation-specific HTTP header parameters SHOULD be documented.

Example 35. General vs operation-specific HTTP headers

Following are examples of HTTP headers that shouldn’t be documented explicitly for each operation:

Accept-Language
BelGov-Trace-Id and BelGov-Related-Trace-Id (documented in Tracing)
Authorization

Examples of headers that should be specified on operations that support them:

ETag
If-Modified-Since

Rule: doc and refData resources [doc-refdata]

The OpenAPI specification file and other API documentation SHOULD be placed under a special doc resource under the API root location. Access to these documentation resources SHOULD be granted to any user or potential user of the API.

The swagger specification file is, by convention, named swagger.json or swagger.yaml. Root OpenAPI 3.0 documents SHOULD be named openapi.json or openapi.yaml, as specified in the OpenAPI 3.0 specification.

Resources representing reference data (code lists) specific to an API SHOULD be placed under a refData resource. As reference data is typically static, consider supporting Caching headers for these resources.

Note that these are exceptions to the rule that API resource URLs shouldn’t have a file extension.

Example 36. doc and refData resources

 /doc
     /openapi.json
     /openapi.yaml
     /<optional other documentation>
 /refData
     /<list1OfCodes>
        /<code1>
        /<code2>
        /...
     /<list2OfCodes>
        /...
 /<resource1>
     /...
 /<resource2>
     /...
 ...

Rule: default values [oas-defaul]

Absent optional properties in a request are set by the API provider to their default value if one is specified in the OpenAPI specification.

Rule: Naming of path parameters [path-param]

Path parameters SHOULD use lowerCamelCase notation.

KO OK

KO	OK
`paths: /employers/{EmployerId}: # ....`	`paths: /employers/{employerId}: # ....`

paths:
  /employers/{EmployerId}:
    # ....

paths:
  /employers/{employerId}:
    # ....

Rule: Add examples in OpenAPI [oas-exampl]

Add examples to an OpenAPI document.

Examples SHOULD be provided under the example or examples OpenAPI properties rather than in a description. examples allows specifying multiple examples, but can’t be used within schema definitions.

Example values MUST be schema-valid.

OpenAPI 2.0 only allows a single example per media type under examples. Any additional examples should be put in external documentation or specified using a x-examples custom extension following the OpenAPI 3.0 format.

Example 37. Examples in OpenAPI

OpenAPI 3.0

/enterprises/{enterpriseNumber}:
  get:
    operationId: getEnterprise
    parameters:
    - in: path
      name: enterpriseNumber
      required: true
      schema:
        type: string
    responses:
      "200":
        description: successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Enterprise'
            examples:
              success:
                description: Successful response with enterprise data
                value: {
                  "name": "Proximus",
                  "enterpriseNumber": "0202239951"
                }

OpenAPI 2.0

/enterprises/{enterpriseNumber}:
  get:
    operationId: getEnterprise
    parameters:
    - in: path
      name: enterpriseNumber
      required: true
      type: string
    responses:
      "200":
        description: successful operation
        schema:
          $ref: '#/definitions/Enterprise'
        examples:
          application/json:
            {
              "name": "Proximus",
              "enterpriseNumber": "0202239951"
            }

Rule: Component definitions [oas-comp]

Duplication of definitions (schemas, responses, parameters, etc.) SHOULD be avoided. Rather, define them once under components, from which they can be referenced (using $ref).

All component names SHOULD be defined in American English and use UpperCamelCase notation. For abbreviations as well, all letters except the first one should be lowercased.

Do not use underscores (_), hyphens (-) or dots (.) in a component name, nor use a digit as first letter.

Rule: Reusable OpenAPI files [oas-reuse]

Instead of specifying everything directly in the openapi.yaml (or swagger.yaml) file of an API, OpenAPI allows to reference data types (schemas) and other components from other files. These files SHOULD follow the Swagger/OpenAPI file format as well and may include data type (schema) definitions, but also other component types like parameters, path items, request bodies and responses.

To work around limitations of certain tools, a conversion step to inline the definitions into the openapi.yaml file may be necessary.

Duplication of types in multiple APIs SHOULD be avoided. Rather, put the type in a reusable OpenAPI file. Files reusable from multiple APIs SHOULD be organized in this structure:

<domain>/<version>/<domain-version>.yaml
<domain>/<subdomain>/<version>/<domain-subdomain-version>.yaml

Definitions SHOULD be grouped per (sub)domain in a file. Each file has its own lifecycle, with a major version number in its directory and file name, that is increased when backwards compatibility is broken. This version, with optionally a minor and patch version added to it, MUST be specified in the info section in the swagger file as well.

While it is not strictly necessary for external definitions to be put in a valid OpenAPI file, doing so makes it possible to use standard OpenAPI/Swagger tooling on them.

Example 38. Reusable OpenAPI file

/person/identifier/v1/person-identifier-v1.yaml

openapi: "3.0.3"
info:
  title: person-identifier
  description: data types for person identifiers
  version: "1.1.2"
paths: {} # empty paths property required to be a valid OpenAPI file
components:
  schemas:
    Ssin:
      description: "Social Security Identification Number issued by the National Register or CBSS"
      type: string
      pattern: \d{11}

A type can be referenced from another OpenAPI file:

"$ref": "./person/identifier/v1/person-identifier-v1.yaml#/components/schemas/Ssin"

Rule: Common definitions for Belgian government institutions [oas-comdef]

Common definitions for use by Belgian government institutions are maintained in the openapi-* GitHub repositories, released as zip archives, organized per domain and also available in Maven Central. Types in these schemas SHOULD be used instead of defining your own variants.

The technical types referenced in this style guide are available in the openapi-common and openapi-problem repositories. Other types for business concepts commonly used by Belgian government institutions are available in other repositories.

10.2. JSON data types

Rule: Naming of data types (schemas) [oas-types]

As stated in [oas-comp], data type (schema) names should use UpperCamelCase and American English.

In addition, data type names SHOULD NOT include overly generic terms like info(rmation) and data.

A data type name SHOULD refer to the business meaning rather than how it is defined.

KO	OK
SSIN	Ssin
CustomerInformation	Customer
LanguageEnumeration	Language

SSIN

Ssin

CustomerInformation

Customer

LanguageEnumeration

Language

Rule: Data type description [oas-descr]

The description property MAY provide a textual description of a JSON data type. The title property MUST NOT be used because it hides the actual data type name in visualization tools like Swagger UI.

KO OK

KO	OK
`Pet: title: a pet in the pet store type: object`	`Pet: description: a pet in the pet store type: object`

Pet:
  title: a pet in the pet store
  type: object

Pet:
  description: a pet in the pet store
  type: object

additionalProperties can be used to put restrictions on other properties of a JSON object than those specified in the schema.

Rule: additionalProperties [addi-prop]

additionalProperties SHOULD be used exclusively to describe an object representing a map of key-value pairs. The keys of such maps don’t need to respect the naming rules for JSON properties (lowerCamelCase and English).

An example is the description a map of embedded resources, as described in Embedding resources. Other uses of additionalProperties than for maps are to be avoided, in order to support schema evolution.

Rule: Required properties [prop-req]

You can declare properties of a JSON object as mandatory by adding them to the required list.

Any properties listed in required MUST also be declared in the object’s properties, either inline or in a referenced subschema.

While undeclared required properties are permitted by the JSON Schema standard, they are most often the result of an error in the OpenAPI document (typo, oversight when renaming a property, …). This rule allows linting tools to mark such errors.

Example 39. Required properties

GOOD BAD

GOOD	BAD
`type: object properties: givenName: type: string required: [givenName]`	`type: object properties: givenName: type: string required: [firstName] # firstName isn't explicitly declared as a property`

type: object
properties:
  givenName:
    type: string
required: [givenName]

type: object
properties:
  givenName:
    type: string
required: [firstName] # firstName isn't explicitly declared as a property

Rule: Unknown input [req-valid]

An API SHOULD refuse unknown input, i.e. unknown body (JSON) properties in the payload or unknown query request parameters. A Bad Request problem response should be returned with an issue of type urn:problem-type:belgif:input-validation:unknownInput.

If an operation does allow and process input that is not defined in OpenAPI, its description should explicitly indicate this.

In specific situations, where a (known) input is not needed anymore and can be safely ignored:

either it can stay in the API definition with a deprecation flag and a "not used anymore" description
or it can be removed from the API definition as long as the server ignores this specific input.

Unknown HTTP header parameters MUST be accepted.

If unknown request fields would be accepted, certain client errors cannot be recognized by servers, e.g. parameter name typing errors will be ignored and the client’s actual intent will not be met.

Unknown HTTP headers are usually metadata added automatically by technical components that do not change the API’s expected behavior and thereby can be ignored.

Rule: readOnly properties [oas-rdonly]

Properties SHOULD be declared as readOnly: true when appropriate.

This means that the value of the property is managed exclusively by the owning authority, and attempts by a client to modify the value of this property are expected to be ignored or rejected.

Examples are an immutable identifier of a document, properties that are computed from other properties, or that represent a volatile state of a resource.

Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema.

Above guideline is compliant with the definition of readOnly used by the OpenAPI 3.1 Specification.

The OpenAPI 3.0 Specification has a different definition, that allows to omit properties from requests that are both readOnly and required. This has been changed in OpenAPI 3.1 to achieve full compatibility with the JSON Schema Specification. Hence, to be forward-compatible, OpenAPI documents should not depend on this 3.0 behavior.

Rule: Enum values [oas-enum]

A fixed list of possible values of a property can be specified using enum. However, this may make it harder to change the list of possible values, as client applications will often depend on the specified list e.g. by using code generation.

enum SHOULD only be used when the list of values is unlikely to change or when changing it has a big impact on clients of the API.

enum values SHOULD be valid to the schema in which they are defined.

Example 40. Enum declaration

State:
  type: string
  enum:
  - processing
  - failed
  - done

When defining a type for an identifier or code, like the above example, the guidelines under Identifier apply, even when not used as a URL path parameter of a document resource.

Rule: Decimals [dec-type]

Decimal numbers for which the fractional part’s precision is important, like monetary amounts, SHOULD be represented by a string-based type, with number as format. Depending on the context, a regular expression can enforce further restrictions like the number of digits allowed before/after comma or on the presence of a +/- sign.

When number would be used as type instead of string, some technologies will convert the values to floating point numbers, leading to a loss of precision and unintended calculation errors.

This problem may also be avoided by using an equivalent integer representation, for example by expressing a monetary amount in Euro cent rather than Euro.

Some more background on why floating point numbers can lead to loss of precision, can be found in this blog post.

Example 41. Number types preserving precision

belgif openapi-money defines a string-based type for monetary values:

MonetaryValue:
  type: string
  format: number # number is a custom string format that is supported by some, but not all tooling
  pattern: '^(\-|\+)?((\d+(\.\d*)?)|(\.\d+))$'  # Variable number of digits, with at least one digit required, before or after the decimal point. Allows both positive and negative values.
  x-examples:
  - "100.234567"
  - "010"
  - "-.05"
  - "+1"
  - "10"
  - "100."
MonetaryAmount:
  description: A monetary amount
  type: object
  properties:
    value:
      "$ref": "#/components/schemas/MonetaryValue"
    currency:
      "$ref": "#/components/schemas/Currency"
  required: [value, currency]
  example:
    value: "0.01"
    currency: "EUR"

It also defines integer-based types specific for monetary amounts expressed in Euro cent:

EuroCentPositiveAmount:
  description: Money amount in Euro cents >= 0
  type: integer # representation as Euro cent instead of Euro to avoid floating point rounding problems and need for custom 'number' format
  minimum: 0

EuroCentAmount:
  description: 'Money amount in Euro cents, also allows negative amounts.'
  type: integer # representation as Euro cent instead of Euro to avoid floating point rounding problems and need for custom 'number' format

10.3. Tools

Following tools can be used to edit OpenAPI files

Name	Link	Description
Swagger UI	https://swagger.io/swagger-ui/	Browser application. Graphical and text view of Swagger files. Does not support references to external files.
Zalando’s Swagger plugin	https://github.com/zalando/intellij-swagger	Open Source plugin for IntelliJ. Text-only editor.
Stoplight Studio	https://github.com/stoplightio/studio/releases	Commercial editor with a free version. Graphical and text view, both web based or as desktop application. Supports validation of API style guides (Spectral).
42Crunch OpenAPI (Swagger) Editor for VS Code	https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi	Open Source plugin for Visual Studio Code. Text editor with SwaggerUI preview and multi-file support.
42Crunch OpenAPI (Swagger) Editor for IntelliJ	https://plugins.jetbrains.com/plugin/14837-openapi-swagger-editor	Plugin for IntelliJ. Text editor with multi-file support.
IntelliJ OpenAPI Specifications	https://www.jetbrains.com/help/idea/openapi.html	Plugin bundled with IntelliJ Ultimate (commercial). Text editor with SwaggerUI preview and multi-file support.

Name

Link

Description

Swagger UI

https://swagger.io/swagger-ui/

Browser application. Graphical and text view of Swagger files. Does not support references to external files.

Zalando’s Swagger plugin

https://github.com/zalando/intellij-swagger

Open Source plugin for IntelliJ. Text-only editor.

Stoplight Studio

https://github.com/stoplightio/studio/releases

Commercial editor with a free version. Graphical and text view, both web based or as desktop application. Supports validation of API style guides (Spectral).

42Crunch OpenAPI (Swagger) Editor for VS Code

https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi

Open Source plugin for Visual Studio Code. Text editor with SwaggerUI preview and multi-file support.

42Crunch OpenAPI (Swagger) Editor for IntelliJ

https://plugins.jetbrains.com/plugin/14837-openapi-swagger-editor

Plugin for IntelliJ. Text editor with multi-file support.

IntelliJ OpenAPI Specifications

https://www.jetbrains.com/help/idea/openapi.html

Plugin bundled with IntelliJ Ultimate (commercial). Text editor with SwaggerUI preview and multi-file support.

Following tools can be used to generate server stubs and API client libraries from OpenAPI specification files.

Name	Link	Comments
openapi-generator	https://openapi-generator.tech/	Started as fork of swagger-codegen.
swagger-codegen	https://github.com/swagger-api/swagger-codegen

Name

Link

Comments

openapi-generator

https://openapi-generator.tech/

Started as fork of swagger-codegen.

swagger-codegen

https://github.com/swagger-api/swagger-codegen

Following tools allow to verify REST styleguide rules for an OpenAPI document:

Name	Link	Comments
belgif-rest-guide-validator	https://github.com/belgif/rest-guide-validator	Open Source Maven Plugin to validate OpenAPI document against rules in this guide
Spectral	https://stoplight.io/open-source/spectral	Open Source tool (javascript-based) to enforce REST styleguide rules. Note: There currently is no implementation of this REST guide for Spectral.

Name

Link

Comments

belgif-rest-guide-validator

https://github.com/belgif/rest-guide-validator

Open Source Maven Plugin to validate OpenAPI document against rules in this guide

Spectral

https://stoplight.io/open-source/spectral

Open Source tool (javascript-based) to enforce REST styleguide rules.

Note: There currently is no implementation of this REST guide for Spectral.

10.4. References

Name	Link
OpenAPI 2.0 specification	http://spec.openapis.org/oas/v2.0.html
OpenAPI 3.0 specification	http://spec.openapis.org/oas/v3.0.3.html
Swagger	https://swagger.io/docs/specification/2-0/basic-structure/

Name

Link

OpenAPI 2.0 specification

http://spec.openapis.org/oas/v2.0.html

OpenAPI 3.0 specification

http://spec.openapis.org/oas/v3.0.3.html

Swagger

https://swagger.io/docs/specification/2-0/basic-structure/

11. Hypermedia controls

Thanks to hypermedia controls a client can navigate through the REST API without hardcoding URIs to specific resources. It suffices to know a limited set of entry points and navigate to the desired information. This adds flexibility to the evolution of the API and increases loose coupling between client and server.

11.1. Links

Rule: Links to self and other resources [hyp-links]

When referencing another resource within the same API, a link SHOULD be added using the href attribute.

It is NOT RECOMMENDED to link to resources in other APIs to avoid a tight coupling between the APIs, unless the link target is guaranteed to remain very stable (like the href links to standard problem types [err-problem]).

Each resource MAY also contain its own location in a self attribute at root level of the JSON document.

URIs SHOULD always be absolute.

For brevity, most URIs in the style guide examples are shortened, but in reality URIs should always be absolute.

All href hyperlinks are derived from this minimal link type:

HttpLink JSON data type (from common-v1.yaml)

HttpLink:
  description: A base type of objects representing links to resources.
  type: object
  properties:
    href:
      description: Any absolute URI that is using http or https protocol
      type: string
      format: uri
      readOnly: true

self hyperlinks are derived from the following type:

SelfLink JSON data type (from common-v1.yaml)

SelfLink:
  description: A base type representing a link to the resource's own location within its representation
  type: object
  properties:
    self:
      description: Absolute URI (http or https) to the the resource's own location.
      type: string
      format: uri
      readOnly: true

Links should not be used in request bodies in a PUT, POST or PATCH context, as indicated by the readOnly: true property. In a JSON response, they can be added anywhere.

Example 42. Resource links

GET https://api.socialsecurity.be/demo/v1/companies/1

{
   "self": "/companies/1"
   "owner": {
      "ssin": "12345678901",
      "href": "http://example.org/v1/people/12345678901"
   },
   "website": "https://wwww.mycompany.com"
}

PATCH https://api.socialsecurity.be/demo/v1/companies/1

{
   "owner": {
      "ssin": "12345678902"
   },
   "website": "https://wwww.mynewwebsite.com"
}

The corresponding JSON data type includes the link types using allOf. As website isn’t a reference to another API resource, it is not defined using the HttpLink type.

components:
  schemas:
    Company:
      allOf:
      - "$ref": "./common/v1/common-v1.yaml#/components/schemas/SelfLink"
      - type: object
        properties:
          owner:
            "$ref": "#/components/schemas/PersonReference"
          website:
            type: string
            format: uri
    PersonReference:
      allOf:
        - "$ref": "./common/v1/common-v1.yaml#/components/schemas/HttpLink"
        - type: object
          properties:
            ssin:
              "$ref": "./person-identifier/v1/person-identifier-v1.yaml#/components/schemas/Ssin"

Hyperlinks for Pagination inside collections and self-references should use a simple URI value in combination with their corresponding link relations (next, prev, first, last, self) instead of the extensible link type.

Example 43. Pagination links

{
   "self": "/companies?page=2&pageSize=10",
   "prev": "/companies?page=1&pageSize=10",
   "next": "/companies?page=3&pageSize=10"
}

The use of Web Linking and Hypertext Application Language (HAL) is not recommended.

12. Reserved words

A list of reserved words exists for common used practices

12.1. Query parameters

Term

Description

Example

Ref

page

When a collection resources is paged, use this parameter to request a specific page. Page numbers are 1-based.

?page=3&pageSize=20

pageSize

When a collection resources is paged, use this parameter to specify the page size.

?page=3&pageSize=20

Multi-language descriptions

The standard search parameter to do a full-text search.

?q=Belgacom

Filtering

select

Filter the resource properties to the ones specified.

?select=(name,address)

Consult (Document)

sort

Multi-value query param with list of properties to sort on. Default sorting direction is ascending. To indicate descending direction, the property may be prefixed with -.

?sort=age&sort=-name

Collection

embed

Request to embed subresource

?embed=mainAddress

Embedding resources

lang

language to filter multi-language descriptions

?lang=fr

12.2. JSON properties

Term Description Example Ref

The next-reference contains the absolute URL of the next page in a paged collection result.

"next": "/companies?page=3&pageSize=2"

The previous-reference contains the absolute URL of the previous page in a paged collection result.

"prev": "/companies?page=3&pageSize=2"

self

The self-reference contains the absolute URL of the resource itself.

"self": "/companies/202239951"

href

A reference (absolute URL) to another resource.

"href": "/companies/202239951"

first

A reference (absolute URL) to the first page in a paged collection result.

"first": "https://api.socialsecurity.be/demo/v1/companies?pageSize=2"

last

A reference (absolute URL) to the last page in a paged collection result.

"last": "https://api.socialsecurity.be/demo/v1/companies?page=4&pageSize=2",

items

an array with the items of a collection result.

Collection

total

the total number of items in a collection result, after filtering.

Collection

page

the index of a page in a paged collection result

pageSize

the maximum number of items in a page of a paged collection result.