What to think about before writing API Design Guidelines

by / Tuesday, 29 May 2018 / Published in Blog
UST Global as sponsoring partner for Alfresco Day Madrid 2018
keensoft UST Global in Technovation Challenge final event

During the last years, API as product approach has been adopted by many companies to expose or sell their services in the Internet. Using a winning combination like OpenApis for description and apigee for API Management, is helping organisations to adopt this strategy faster and safer. However, before thinking in the technical part, it’s required to compile a set of guidelines to describe how REST APIs are working for a concrete scenario. This document will guide developers from both parts (consumers and producers), as it’s focused on specifying all the rules of the interaction.

Additionally, when building Cloud Native Applications, API First is a must. API first means that everything you do revolves around the idea that what you are building is an API to be consumed by client applications and services, including mobiles and things. As stated by Adobe, three principles of API First Design are:

  • Your API is the first user interface of your application
  • Your API comes first, then the implementation
  • Your API is described (and maybe even self-descriptive)

Hence, writing an API Design Guidelines document is the first step to build a coherent services API.

Every large company with a public API is sharing their version of the API Design Guidelines:

Since there are different options to solve particular interactions, as described in this sample material, a great part of the guidelines can be extracted or derived from Internet and International Standards.

API Design Guidelines definition

For document semantics, formatting and naming, keywords should be interpreted as described in RFC 2119 – Key words for use in RFCs to Indicate Requirement Levels

HTTP Protocol

URIs should follow RFC 3986 – Uniform Resource Identifier (URI): Generic Syntax specification, including scheme, authority, path, query and fragment components.

URIs templates, including variable fields, should be expressed according to RFC 6570 – URI Template {variable}

HTTP headers should be defined or referenced from RFC 7231 – Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, including Accept, Accept-Charset, Content-Language, Content-Type, Link and Location (usually not used due to HATEOAS approach) and Prefer.

Warning headers, commonly used to report about deprecated APIs, should follow RFC 7234 – Hypertext Transfer Protocol (HTTP/1.1): Caching

RFC 6585 – Additional HTTP Status Codes introduces new codes, as “429 Too Many Requests”. To prevent abuse, it is standard practice to add some sort of rate limiting to an API, where this status code fits perfectly.

To update an object incrementally, PATCH verb as described in RFC 5789 – PATCH Method for HTTP should be used.

JSON Payload

Despite REST APIs payload can be expressed using different formats, JSON is a de facto standard.

The data model for representation in JSON should conform to RFC 7159 – The JavaScript Object Notation (JSON) Data Interchange Format.

When using links inside JSON payload, two alternatives are recommended:

Since JSON data types only include String, Number, Object, Arrays, Boolean and Null, Date and Time formats should be defined following RFC 3339 – Date and Time on the Internet: Timestamps (ISO 8601)

Providing standard internationalisation units and tags is covered by several documents:


A RESTful API should be stateless: request authentication should not depend on cookies or sessions. Instead, each request should come with authentication credentials.

If HTML Basic Authentication fulfils your security requirements, it should be deployed following RFC-7617 – The ‘Basic’ HTTP Authentication Scheme.

However, many of the platforms are using an api key as credentials token. This api key can be managed internally by the service, but when using OAuth 2.0, following considerations should be followed:

Additional topics

CORS (Cross-Origin Resource Sharing) should be supported, understanding the Origin request header and the Access-Control-Request-Method request header.

All APIs should support explicit versioning, by using de facto standard Semantic Versioning 2.0.0

Final recap

There is no Internet standard for API design, as no one found an standard that works in all cases. Hence, before going on with the exposition of your data model, some decisions has to be taken: formats to be accepted, authentication schemes or deprecation policy are some samples for that. Anyway, although defining your API Design Guidelines document is a matter of choice, many questions can be answered directly by adopting Internet Standards.

Find some time before exposing your APIs to write down some short of instructions for consumers and producers. It will be worth it in the future!

Unidad de negocio, keensoft

Tagged under: ,

Leave a Reply