Deep Dive into building APIs






The effectiveness of an API is determined by it’s usability.

my cloud

If developers can easily use the API then the API can graciously claim to have achieved its purpose. An API is usable if it accepts straight forward inputs, gives valuable feedback and is predictable. A predictable API is an API who’s users know what to expect. Usability is achieved by implementing the appropriate API design, approriate and consistent data formats, proper documentation, specification and/or definition.

In this post, we will discuss a few considerations in building APIs such as types, styles and various standards. We will delve into:

  1. API designs
  2. API data formats
  3. API specification and styles
  4. API definitions
  5. API documentation
  6. API mocking
  7. API testing

1. API Designs






Fun fact




i. JSON(Javascript Object Notation)


  "title": "Json example",
      {"type": "string"}
    {"type": "boolean"},

ii. XML(Extensible Markup Language)




my cloud

iii. GraphQL

GraphQL is not just a data format, but is stated as:


GraphQL provides a way to expose resources, evolve the data and retrieve it on an as-needed basis. A graphql API is largely driven by the application’s data requirements. GraphQL touts these advantages over a traditional REST API:

  • Allows the client to control what data it receives. Less data means faster responses.
  • The client can query for, and get back more than one resource type
  • A graphql API can have just a single endpoint and can be evolved with minimal breaking changes

A graphql request/query uses a custom json-like syntax, and returns a json response. The returned data has a similar structure to the request.

  allFilms {
    films {


  "data": {
    "allFilms": {
      "films": [
          "id": "ZmlsbXM6MQ==",
          "title": "A New Hope",
          "director": "George Lucas"
          "id": "ZmlsbXM6Mg==",
          "title": "The Empire Strikes Back",
          "director": "Irvin Kershner"

Response from the graphiql demo.

The custom request structure may require that you use a graphql specific tool to explore or test an API. You can find a comprehensive list of tools here, and see what developers find challenging on this twitter thread. A few of these tools include:

  • GraphiQL - browser based GraphQL IDE
  • Relay - javascript framework for building react applications powered by GraphQl
  • graphql-tools - a set of javascript utilities for building and mocking GraphQL APIs

3. API specification and styles


3.1. A Note on REST + JSONAPI

During the design of a REST API, it is very easy to get lost in the ‘how’ of the API’s implementation. This is especially true if you’re the one who will be building out the functionality. As a backend developer, it is only natural that you think about the API based on what data it will handle and how that data will be stored. The problem with this is that our REST resources become coupled with application objects and consequently, database tables.

So, what exactly is a resource? According to Fielding:


If you can name it, it can be a resource! Simple, right? This article is an excellent resource on choosing resources and how to structure URIs.

So, is it possible to have non-resource routes/endpoints? And if yes, how do you handle them? And before all that, is it still a REST API? Layering on jsonapi adds an extra level of complexity. Resources in jsonapi are represented by resource objects:

"data": {
  "type": "users",
  "id": "101",
  "attributes": {
    "name": "user name"
  "relationships": {},
  "links": {},
  "meta": {}

The type and id are required for all responses from the API, and have the added constraint that:

Within a given API, each resource object’s type and id pair MUST identify a single, unique resource.

The only time the id is not required is when creating a new resource on the server - no client-generated ids. Since the id is sent along in the data of a PUT|PATCH this (might)necessitates a change in the URL scheme. Instead of PATCH /resources/1 this becomes PATCH /resources with the id extracted from the request body. That, or we have to accept some redundancy on our endpoints.

The type and id are easy enough to populate when our resources map closely to our database tables, things get complicated otherwise. A common endpoint where this will occur is authentication, where a user expects to sign-in and get an access token. In this case, the type can be set as ‘token’, but what should the id be? And, does it really make sense to serialize the token into attributes? From discussions we have 3 choices:

  1. We could clobber the token into a resource object as discussed here.
  2. Ditch the spec and return a flat json object
  3. Send the token in the top-level meta object, which is meant for “non-standard meta-information” (whatever that means). By sending back a response without primary data, it implies that the response doesn’t represent a resource.

The JSON:API spec adds constraints to a REST API that amplifies the choice of how we structure our resources. It might also need us to jump through a few hoops to structure the responses just right. While the urge to conform to the spec is high, there are times when breaking out will just make sense.

4. API Definition


i. RAML - RESTful Markup Language


ii. OpenAPI


iii. API Blueprint


5. API Documentation


Documentation tool Demo source
swagger Swagger Demo Swagger/OpenAPI
ReDoc ReDoc Demo OpenAPI
DocBox Wobble Demo Markdown
Apiary Apiary Demo API Blueprint Demo Swagger / OpenAPI Spec
Gelato Gelato Demo Markdown OpenAPI, Swagger, RAML
LucyBot LucyBot Markdown, Open-API



local tools online tools rails specific tools
mountebank mockable webmock
WireMock Mocky vcr
MockServer mockAPI  
json-server Sandbox  



Here’s a list of some common API testing tools.

  1. SoapUI
  2. Katalon Studio
  3. postman
  4. Tricentis Tosca
  5. Apigee
  6. JMeter
  7. Rest-assured
  8. Assertible

Want to have a quick chat?
