Skip to content

Latest commit

 

History

History
106 lines (70 loc) · 6.01 KB

data-definitions.md

File metadata and controls

106 lines (70 loc) · 6.01 KB

Data Definitions and Standards

Text encoding

APIs should represent all texts in the UTF-8 encoding.

JSON

Primitive values MUST be serialized to JSON following the rules of RFC8259 and, as stated in the standard, JSON text MUST be encoded using UTF-8 RFC3629.

JSON can represent four primitive types strings, numbers, booleans, and null and two structured types objects and arrays. Concepts like Date and Time need to be represented using these types.

Data transfer objects

Data transfer objects, or DTOs, are objects used to wrap resource definitions in request/response objects along with additional information.

In a response body, you should return a JSON object, not an array, as a top level data structure to support future extensibility. This would allow you to extend your response and, for example, add a server side pagination attribute.

Bad response body

[
  { "id": "1", "name": "Einar"   },
  { "id": "2", "name": "Erlendur"},
  { "id": "3", "name": "Valdimar"}
]

Good response body

{
  "users":[
    { "id": "1001", "name": "Einar"},
    { "id": "1002", "name": "Erlendur"},
    { "id": "1003", "name": "Valdimar"},
  ]
}

// With pagination fields
{
  "users":[
    { "id": "1001", "name": "Einar"},
    { "id": "1002", "name": "Erlendur"},
    { "id": "1003", "name": "Valdimar"},
  ],
  "nextCursor": "aWQ6MTAwNA==",
}

Pagination

All services should support pagination from the start, even though the dataset is small. It is harder to add it later on as it would break the service interface for current users.

Pagination should be implemented using Cursor. Cursor pagination solves the missing or duplication of data problems that the typical offset method has. Cursor pagination returns a cursor in the response, which is a pointer to a specific item in the dataset. This pointer needs to be a unique sequential field (or fields).

When implementing cursor pagination a field called nextCursor is returned in the response object. This field is a Base64 encoded string. Having it encoded makes it uniform while providing flexibility to implement different cursor logic between different endpoints. In the example above the nextCursor field is a Base64 encoding the value id:1004, meaning the server is using the id field of the user object as a pointer to next item.

To indicate there are no more results the value of nextCursor is set to the empty string: "nextCursor": "".

Optionally, an API can also provide the field totalCount to indicate to the client how many results are available.

Pagination query parameters

For an API to support pagination it needs to support the following query parameters:

  • cursor - The client provides the value of nextCursor from the previous response to set the start of next page of results.
  • limit - Limits the number of results in a request. The server should have a default value for this field.

National identifier

Icelandic individuals are uniquely identified by a national identifier called kennitala. When referring to this identifier in URIs, requests, or responses, APIs should use the name nationalId. Its value is usually represented to users in the form ######-#### but APIs should use the form ########## at all times.

Language and currency

  • Languages - When specifying a language please use the ISO-639-1 (two letter) standard. See: 639-1 codes.
  • Currencies - When specifying currency codes please use the ISO-4217 standard. See: 4217 codes.
    • Amount - Use the format [0-9]+(.[0-9]+)? to represent an amount. Separate amount and currency in different fields. Example amount: 1250.23.

Date and time

Date and time values should be represented in a string, as described in the RFC3339 proposed standard. The standard defines a profile of ISO 8601 for use in Internet protocols. See: Section 5.6 for Date/Time Format.

Summary for date and time

Date and time should be represented as a string using the format yyyy-MM-ddThh:mm:ss.sssZ. Where

  • yyyy represents year, (four-digits).
  • MM represents month, (two-digits 01 - 12).
  • dd represents day of month, (two-digits 01 - 31).
  • hh represents hour, (two digits 00 - 24).
  • mm represents minute, (two digits 00 - 59).
  • ss represents second, (two digits 00 - 59).
  • sss represents a decimal fraction of a second, (one or more digits).
  • Z represents a time zone offset specified as Z (for UTC) or either + or - followed by a time expression hh:mm.

Icelandic local time can be represented with Z because Iceland follows the UTC +00:00 all year round, which is the same as GMT.

Examples:

  • 1985-04-12T23:20:50.52Z represents 20 minutes and 50.52 seconds after the 23rd hour of April 12th, 1985 in UTC.
  • 1996-12-19T16:39:57-08:00 represents 39 minutes and 57 seconds after the 16th hour of December 19th, 1996 with an offset of -08:00 from UTC (Pacific Standard Time). Note that this is equivalent to 1996-12-20T00:39:57Z in UTC.

Timestamp data

All returned data should contain the field createdTimestamp and it's value should be the date and time when the data was created. This is important because of different caching rules and different viewpoints on when data should be considered obsolete.