Data Formats

Must: Use JSON as the Body Payload

JSON-encode the body payload. The JSON payload must follow RFC-7159 by having (if possible) a serialized object as the top-level structure, since it would allow for future extension. This also applies for collection resources where one naturally would assume an array. See the pagination section for an example.

Could: Use other Media Types than JSON

If for given use case JSON does not make sense, for instance when providing attachments in form of PDFs, you should use another, more sufficient media type. But only do this if you can not transfer the information in JSON.

Must: Use Standard Date and Time Formats

JSON Payload

Read more about date and time format in Json Guideline.

HTTP headers

Http headers including the proprietary headers. Use the HTTP date format defined in RFC 7231.

Could: Use Standards for Country, Language and Currency Codes

Use the following standard formats for country, language and currency codes:

• ISO 3166-1-alpha2 country codes

  • (It is “GB”, not “UK”, even though “UK” has seen some use at Zalando)

• ISO 639-1 language code

  • BCP-47 (based on ISO 639-1) for language variants

• ISO 4217 currency codes

Could: Use Application-Specific Content Types

For instance, application/x.zalando.article+json. For complex types, it’s better to have a specific content type. For simple use cases this isn’t necessary. We can attach version info to media type names and support content negotiation to get different representations, e.g. application/x.zalando.article+json;version=2.