Pimp my API

Two contradictory approaches to API: built a beautiful, standard REST interface vs. rely on query facade called GraphQL? Which way to go? Decide yourself! :)

Swagger

This powerful tool is too commonly used only for generating nice-looking documentation for API. Basically, swagger is for defining the API interfaces using simple, domain-driven JSON language.

Editor is only one tool from the toolkit but other ones are:

• codegen – for generating the source code scaffold for your API – available in many different languages (node, ruby, .NET, PHP)
• ui – most known swagger tool for generating useful and nice looking interactive documentation.

Everything starts with a specification file describing all the Entities and interfaces for the REST API. Please take a look at the example below:

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "produces": [
      "application/json",
      "text/html"
    ],
    "responses": {
      "200": {
        "description": "pet response",
        "schema": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Pet"
          }
        }
      },
      "default": {
        "description": "error payload",
        "schema": {
          "$ref": "#/definitions/ErrorModel"
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "type": "array",
      "items": {
        "type": "string"
      },
      "collectionFormat": "csv"
    }
  ]
}

$ref relates to other entities described in the file (data models, structures etc). You can use primitives as the examples and return values (bool, string …) as well as hash-sets, compound objects and lists. Swagger allows you to specify the validation rules and authorization schemes (basic auth, oauth, oauth2).

{
  "oauth2": {
    "type": "oauth2",
    "scopes": [
      {
        "scope": "email",
        "description": "Access to your email address"
      },
      {
        "scope": "pets",
        "description": "Access to your pets"
      }
    ],
    "grantTypes": {
      "implicit": {
        "loginEndpoint": {
          "url": "http://petstore.swagger.wordnik.com/oauth/dialog"
        },
        "tokenName": "access_token"
      },
      "authorization_code": {
        "tokenRequestEndpoint": {
          "url": "http://petstore.swagger.wordnik.com/oauth/requestToken",
          "clientIdName": "client_id",
          "clientSecretName": "client_secret"
        },
        "tokenEndpoint": {
          "url": "http://petstore.swagger.wordnik.com/oauth/token",
          "tokenName": "access_code"
        }
      }
    }
  }
}

Last but not least swagger OpenAPI specification format has become more and more a standard and should be considered when starting new API projects. It’s supported by many external tools and platforms – including Amazon API Gateway.

GraphQL

Modeling great REST API is hard, using and supporting changes in API over the time is sometimes even harder. GraphQL (http://graphql.org) is a query language, a proposition to a new way of thinking about APIs. It is already used by the Vue Storefront – progressive web app frontend – to get data from the backend.

Widely used REST APIs are organized around HTTP endpoints. GraphQL APIs are different, they are built in terms of types and fields and relations between them. It gives clients the ability to ask for what they need directly instead of many different REST requests. All necessary data will be queried and returned with a single call.

Data definition:

type Project {
  name: String
  tagline: String
  contributors: [User]
}

Sample query:

{
  project(name: "GraphQL") {
    tagline
  }
 }

Query result:

{
  "project": {
    "tagline": "A query language for APIs"
  }
}

GraphQL was developed internally by Facebook in 2012 and open-sourced 3 years later with Relay, JavaScript framework for building data-driven React applications. Nowadays the GraphQL ecosystem is growing rapidly, both server and frontend libraries are available for many programming languages and developers have dedicated tools for GraphQL API design. Many other organizations, including Github, Pinterest and Shopify are adopting GraphQL because of its benefits.

Swagger UI generates a nice-looking specification for your API along with a “try-it-out” feature for executing API calls directly from the browser.

This post is a part of my book “Microservices architecture for eCommerce”. Please don’t hesitate and grab your free copy today!