API Media Type Guidelines¶

Introduction¶

A media type (also known as MIME type) indicates the nature and format of a document, file, or assortment of bytes. Media types are defined and standardized in IETF's (RFC6838).

This page offers guidelines surrounding media types for APIs. Rules listed in this document relate to JSON documents and HTTP operations. Business units are free to further refine the rules described herein.

At the end of this section you find an example that follows all recommendations of this guideline.

API SHOULD use the media type 'application/json' [100]¶

It is recommended using the media type application/json for exchanging data.

JSON documents SHOULD conform to I-JSON - RFC7493, a profile of the original JSON specification with the purpose of solving some interoperability issues.

It mandates:

• documents to be encoded using UTF-8
• object field names to be unique
• expectations on double precision

API SHOULD use the following document structure [101]¶

This section describes the structure of an API document. In the following sections, an API document is often referred to as 'document'.

API SHOULD use a top-level JSON object [101.1]¶

The root of every document SHOULD contain a JSON object.

The recommendation is to use a JSON object at the top level to improve the extensibility of the API. For example, supporting pagination of a returned collection.

API SHOULD use the defined document structure [101.2]¶

A response document SHOULD contain at least one of the following top-level members:

• data: data representing the "primary data"
• errors: an array of error objects
• meta: a meta object that contains additional meta-information
• links: a links object related to the primary data

The top-level members data and errors MUST NOT coexist in the same response document.

A request document SHOULD contain at least data.

Request and response documents MAY contain other top-level members.

The "primary data" MUST be represented by [101.3]¶

• a single resource object or null, for requests that target single resources
• an array of resource objects, or an empty array ([]), for requests that target resource collections

API MUST represent resources with resource objects [101.4]¶

The "resource objects" are used in an API to represent REST resources.

The top-level values in a resource object can be:

• JSON primitive types (string, number and Boolean)
• JSON structures types (objects and arrays)

A resource object MAY contain the following top-level members:

• id: the identifier of the resource
• links: a links object that contains links related to the resource
• meta: a meta object that contains additional meta-information about the resource

Fields MUST follow the naming convention [101.4.1]¶

A resource object's properties, primitive or objects, are collectively called its fields.

Fields MAY contain any valid JSON value, including complex data structures involving JSON objects and arrays.

The data type MUST be compliant with the types defined in the OpenAPI specification. Data format SHOULD be compliant with the listed data types and formats in the appendix.

Here is an example of a "device" resource object.

{
  "data": {
    "id": 1,
    "name": "My device",
    "deviceType": {
      "id": "hvac",
      "name": "HVAC device"
    }
  }
}

Another example of a "device" resource object could look like

{
  "data": {
    "id": 1,
    "name": "My device",
    "deviceType": {
      "id": "hvac",
      "name": "HVAC device"
    },
    "links": {
      "self": "https://xcelerator.siemens.cloud/devices/1"
    },
    "meta": {
      "createdBy": "admin@xcelerator.siemens.cloud"
    }
  }
}

A links object SHOULD contain one or more links [101.5]¶

Examples for links included in a links object

• self: a link that identifies the current document
• next: a link that is used for pagination

A link SHOULD be represented according to the defined structure [101.6]¶

A link SHOULD be one of the following:

• a string whose value is a URI-reference [RFC3986 Section 4.1], pointing to the link's target
• a link object
• an array of links typed according to this rule (consider the constraint of empty arrays, null is not applicable).
• null, if the link does not exist.

A link's context is the top-level object, or resource object in which it appears.

Here is an example of a self link with a string value.

{
  ...
  "links": {
    "self": "http://example.com/devices/1"
  }
}

Here is another example of a self link with a query parameter.

{
  ...
  "links": {
    "self": "http://example.com/devices/1?fields=id,name"
  }
}

A link object SHOULD be represented according to the defined structure Fields [101.6.1]¶

A link object is an object that represents a web link.

A link object MUST contain the following field:

• href: a string whose value is a URI-reference [RFC3986 Section 4.1] pointing to the link's target.

A link object MAY also contain any of the following fields:

• rel: a string that indicates the link's relation type. The string MUST be a valid link relation type.
• describedby: a link to a description document, such as, OpenAPI or JSON Schema for the link target.
• title: a string which serves as a label for the destination of a link such that it can be used as a human-readable identifier (for example, a menu entry).
• type: a string that indicates the media type of the link's target.
• hreflang: a string or an array of strings that indicates the language(s) of the link's target. An array of strings indicates that the link's target is available in multiple languages. Each string MUST be a valid language tag [RFC5646].
• meta: a meta object that contains non-standard meta-information about the link.

Here is an example for a link object:

{
  ...
  "links": {
    "mylink": {
      "href": "http://example.com/devices/1",
      "title": "Example link on a specific device",
      "type": "application/json"
    }
  }
}

A JSON document MAY provide meta information [101.7]¶

Meta information can be used to include additional information to a JSON object that is not part of the domain object itself (e.g. "createdBy"). If a (commonly used) meta information field is part of the domain object itself, then it SHOULD be part of the data section and not the meta section.

A meta field MUST contain meta information [101.7.1]¶

Where specified, a meta field can be used to include additional meta-information. A meta field can be placed at the top-level document or at resource-level.

The value of each meta field MUST be a JSON object (a meta object).

meta MUST be represented as JSON object [101.7.2]¶

A meta object SHOULD be used to represent meta information as a JSON object.

Any fields MAY be specified within a meta object.

Here is an example of a meta object with top-level and resource-level meta.

{
  "meta": {
    "copyright": "© Siemens 2024",
    "authors": [
      "Werner",
      "Markus"
    ]
  },
  "data": {
    ...
    "meta": {
      "createdBy": "Thomas"
    }
  }
}

The meta fields SHOULD consider syntax and semantics of common meta information fields [101.7.3]¶

The following table defines commonly used meta information fields that SHOULD be considered when a meta information with a specific semantic is used.

Field names SHOULD apply naming conventions [101.8]¶

Field names used in a document MUST be treated as case-sensitive by API clients and servers. They MUST meet all the following conditions:

• Field names MUST contain at least one character.
• Field names SHOULD use lower camel case, for example, lowerCamelCase. Names consisting of multiple words are concatenated seamlessly, and the first character of every concatenated word is capitalized to keep the member name readable.
• Field names SHOULD use American English.
• Abbreviations and acronyms SHOULD be treated as words, where only the first character is capitalized in case of concatenation. For example, use the abbreviations myId for myIdentifier, and yourXml instead of yourXML. This improves readability in case of concatenated words.

If you apply the field naming convention, your resources can be encoded in URLs too. Field names use only non-reserved, URL safe characters specified in RFC 3986.

Field names MUST use the allowed characters only [101.8.1]¶

Field names MUST start and end with a "globally allowed character" and these characters can be used anywhere in a field name:

• U+0061 to U+007A, "a-z"
• U+0041 to U+005A, "A-Z"
• U+0030 to U+0039, "0-9"

Additionally, the following characters MAY be used anywhere in a field names, except as the first or last character:

• U+002D HYPHEN-MINUS, "-"
• U+005F LOW LINE, "_"

Resource names SHOULD be in lowercase with hyphens [101.9]¶

Resource names in an URL path (including resource names) SHOULD be lower case words separated by hyphens (“kebab-case”).

Parameters in the path MAY contain capital letters and MUST be treated case sensitive.

Here is an example of the requests

GET user-mgmt/user-groups/apiDevelopers/users HTTP/1.1

and

GET user-mgmt/user-groups/APIdevelopers/users HTTP/1.1

are referring to different user groups and will return different results.

The resource name of collections SHOULD pluralize the name of the single resource [102]¶

The name of resource collections SHOULD pluralize the name of included resource. In addition the resource paths are conform to the following example for the resource item:

• Resource collection path: /items
• Resource path of a specific resource: /items/{id}

Complete Example¶

Here is an example response for a collection resource that follows all above recommendations. This example also contains pagination.

{
  "data": [
    {
      "id": 1,
      "name": "My device 1",
      "deviceType": {
        "id": "hvac",
        "name": "HVAC device"
      },
      "links": {
        "self": "https://xcelerator.siemens.cloud/devices/1"
      },
      "meta": {
        "createdBy": "admin@xcelerator.siemens.cloud"
      }
    },
    {
      "id": 2,
      "name": "My device 2",
      "deviceType": {
        "id": "hvac",
        "name": "HVAC device"
      },
      "links": {
        "self": "https://xcelerator.siemens.cloud/devices/2"
      },
      "meta": {
        "createdBy": "admin@xcelerator.siemens.cloud"
      }
    }
  ],
  "links": {
    "self": "https://xcelerator.siemens.cloud/devices?size=2",
    "next": "https://xcelerator.siemens.cloud/devices?number=1&size=2"
  },
  "meta": {
    "page": {
      "totalPages": 50,
      "number": 0,
      "size": 2,
      "elements": 2,
      "totalElements": 100
    }
  }
}