SHOULD use the same model for all operations [38]

One model for both read and create purposes should be used. So the GET operation uses the same schema as the POST operation. This helps to keeps the specification and the code generated from the specification simple. It also avoids having to redefine the object structure which can lead to mistakes. Also not all ‘rules’ about the model can be enforced in the specification/schema. Keeping the model simple allow you to perform all validations and logic in the implementation. If however the create model will differ significantly it is possible to define a specific schema for an operation.

MUST use JSON as payload data interchange format [24]

Use JSON to represent structured (resource) data passed with HTTP requests and responses as body payload. The JSON payload must use a JSON object as top-level data structure (if possible). This allows you to easily extend your response and e.g. add pagination later, without breaking backwards compatibility. See ‘SHOULD use cursor-based pagination’ for an example. Example(s):

{
  "data": [
  {
      "name": "Json",
      "customerNumber": 12345,
      "customerGroup": "internal"
  }
  ]
}

{
    "links": {
        "self": "/salesrequests/v2/123456"
    },
    "data": {
        "id": "123456",
        "date": '2019-05-30T14:45:10Z',
        "status": "CLOSED"
    }
}

More information on how to use links can be found in the Hypermedia section.

SHOULD use times in UTC without local offsets [25]

As defined by the standard, time zone offset may be used, however, we recommend to only use times based on UTC without local offsets. For example 2015-05-28T14:07:17Z rather than 2015-05-28T14:07:17+00:00 (In addition to “MUST use ISO 8601 date and time format”)

MUST use lowerCamelCase for fields [26]

Use camelCase for fields, so eanCode instead of EanCode (which is in PascalCase). This extends to all abbreviations, which are to be treated as regular words (so: itDepartment, xmlId and httpUrl).

SHOULD use enum values in UPPER_SNAKE_CASE [27]

Natural language in UPPER_SNAKE_CASE for a maximum of 3 words should be used if published (ISO) standard codes and market (CIM/EDSN) standard codes are not applicable. See “MUST use published standard codes”.

Example(s):

gender:
  enum:
  - MANNELIJK
  - VROUWELIJK
  - ONBEKEND

SHOULD use open-ended list of values for enumerations [28]

Enumerations are per definition closed sets of values, that are assumed to be complete and not intended for extension. This closed principle of enumerations imposes compatibility issues when an enumeration must be extended. To avoid these issues, we strongly recommend to use an open-ended list of values instead of an enumeration. To specify an open-ended list of values use the marker x-extensible-enum as follows:

Example(s):

status:
  type: string
  description: The phase (moment) the work order is in
  x-extensible-enum:
    - OPEN
    - ACCEPTED
    - CANCELLED

MUST provide API identifiers [29]

Each API specification must be provisioned with a globally unique and immutable API identifier. The following rules applies for identifiers:

Resource identifiers MUST always be named ‘id’ [30]
Resource identifiers MUST remain the same [31]
Resource identifiers MUST be of type string [32]
MUST treat the identifier as opaque string [33]
MAY include a natural identifier [34]

Resource identifiers MUST always be named `id` [30]

id in stead of salesOrderId or eanCode

Resource identifiers MUST remain the same [31]

identifier MUST remain the same even when the provider implementation changes. A “natural” identifier like EAN code for a connection is a good option for this.

Resource identifiers MUST be of type string [32]

Identifiers must always be of type string even when they only consist of numbers.

MUST treat the identifier as opaque string [33]

A consumer must treat the identifier as opaque string and thus not derive any structure or meaning from it.

MAY include a natural identifier [34]

When a natural identifier is available this can be included in a separate field and have the same value as the id. This way the identification always has the same name. If consumer wants to display the natural identifier (like the eanCode) it can use that field while treating the id as opaque and hidden from an end user: {"id": "871689213001727525", "eanCode": "871689213001727525"}

SHOULD use RD coordinate system [35]

Because of continental drift the RD coordinate reference system is most suited for positions in The Netherlands. RD also known as EPSG:28992 (without height) or RDNAP EPSG:7415 (with height) is the predominant CRS used by Stedin applications. For this reason these coordinate reference systems should be used in our APIs by default. In the future the EPSG:4258 (without height) or EPSG:7409 (with height) might become more common. For coordinates of photo’s EPSG:4326 might be more convenient. But the use of anything other than RD or RDNAP should be approved by the Integration Design Authority.

MUST use standard GEO model [36]

The common geo model is available in the repository for standard representation of point, lines and areas.

SHOULD use modificationDate instead of modifiedOn or modifiedAt [37]

Prefer the use of creationDate and modificationDate over alternatives as createdDate or modifiedOn. For the format see also: “MUST use ISO 8601 date and time format”

SHOULD use real world example data [39]

Use real world example data. For example {“eanCode”: “871689213001727525”} instead of {“eanCode”: “123”}

SHOULD end single sentences without a dot [40]

Write single sentences without a dot

For example:

eanCode:
  title: EAN code
  description: The unique identification of this connection (EAN18 code)

SHOULD use single quotes but only when required [41]

Use single quotes but only when required.

For example:

changeDate:
  type: string
  format: date-time
  example: '2019-05-30T14:45:10Z'

SHOULD standardize order of JSON schema fields [42]

administrativeStatus:
  title: Administrative status of the 'slimme meter'
  description: 'AAN = Ingeschakeld, UIT = Uitgeschakeld' 
  type: string
  example: 'UIT'
  enum:
  - AAN
  - UIT

stdn-api-guidelines

API guidelines STDN