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
Read more about date and time format in Json Guideline.
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:
- (It is “GB”, not “UK”, even though “UK” has seen some use at Zalando)
- BCP-47 (based on ISO 639-1) for language variants
Should: Prefer standard Media type name
Previously, this guideline allowed the use of custom media types like
This usage is not recommended anymore and should be avoided, except where it is necessary for cases
of media type versioning. Instead, the standard media type name
application/problem+json for HTTP error details) should be used for JSON-formatted data.
Custom media types with subtypes beginning with
x bring no advantage compared to the standard media type for JSON, and make automated processing more difficult. They are also discouraged by RFC 6838.