Deep Dive into building APIs

APIs are becoming the mainstream way of exposing services to the world and it’s known that using a well-designed API is extremely rewarding, while using a poorly-designed API can be very infuriating. However, when we ourselves strive to build the best-designed APIs possible, we tend to trip up a bit. What aspects of an API should be considered in order to come up with a well designed API? What are the available tools to facilitate the API development process? Wait what is an API?

In order to build an API (Application Programming Interface) we need to understand what it is. The terms in the acronym API are defined as follows

• Application (app) in software terms is computer software designed to perform a group of coordinated functions, tasks, or activities for the benefit of the user.
• Programming (coding) is the process of creating a set of instructions that tell a computer how to perform a task.
• Interface is a shared boundary across which two or more separate components of a computer exchange information.

With that, an API can be defined as a set of subroutine definitions, communication protocols, and tools for building software. The API could be for a web-based system, an operating system, a database system, computer hardware or a software library. The APIs contain building blocks that can be put together by a developer to build a computer program.

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

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 considtent data formats, proper documentation, specification and/or definition.

In this post, we will discuss a few consideration in building API 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

API design refers to the API’s pattern or architecture, how the API is made available to its end users. Having a consistent API design and format is important as it facilitates better API maintenance and implementation. It also enables consumers(developers) to easily use the API as it reduces the learning and implementation curves. There are four primary architectural design styles. Though not mutually exclusive, these designs have a number of differences that are important to note.

i. Uniform Resource Identifier Design. This style allows developers to invoke requests through common HTTP operations like POST, GET, DELETE and PUT which as usually mapped to CRUD (create, read, update and delete) operations. An example of its usage is the REST API architecture which allows one-way interaction centered around a Resource commonly referred to as an object. It works best where data can easily be described as objects that can be manipulated within the CRUD cycle.

ii. Event-Driven Architecture (EDA) Design. As the name suggests, this pattern is centered around events. The events are defined at technical and business level. Those events get triggered by specific actions or API calls. What stands out in the Event-Driven Architecture is that it’s a two-way street. Whereas other systems rely on either the client or the server listening and responding to events, the Event-Driven design requires both client and server to listen to new events. One of the most popular examples of the Event-Driven style is Reactive programming popularised by ReactiveX API thorugh the RxJS library.

iii. Hypermedia Architecture (HA) Design. The Hypermedia Architecture is a middle ground approach between the Event-Driven Architecture and the URI Design — whereas the URI design focuses largely on objects and the requests for them, the Hypermedia Architecture focuses on tasks and the flow between them. A message-oriented design. With hypermedia APIs, the messages passed between components contain more than just data. They also include descriptions of possible actions. This means that actions, as well as data, are loosely coupled making Hypermedia API self descriptive. A good example of an API offered as a service that implements this design is Amazon API Gateway.

iv. Tunneling Style. The Tunneling Style is the oldest of these four styles. It functions as a system of Remote Procedure Calls (RPCs). It can be organized in an XML message format transported over HTTP(XML-RPC), JSON message format transported over HTTP(JSON-RPC), or protocol buffers over gRPC. Notabley, gRPC, developed by google, is advertised for use in connecting services in a micro-services based architecture and connecting mobile devices and web clients to backend services. Tunneling APIs allow for localization of content, where RPC calls are used by distant hosts to request access as if the server providing the data is local.

Fun fact

The ‘g’ in gRPC stand for different things with every gRPC release… good, green, glossy and currently at this writing ‘gizmo’ for version 1.17

2. API DATA FORMATS

This is basically how the API handles interaction between data generation and data requests. There are a number of data formats available and popular in the API world. The following are the most common.

i. JSON(Javascript Object Notation)

JSON is based on the popular Javascript programming language built on two structures; a collection of name/value pairs and an ordered list of values.

{
  "title": "Json example",
  "properties": 
    {"firstName": 
      {"type": "string"}
    },
  "knownValue": 
    {"type": "boolean"},
  "age": 
    {"description": "Age in years","type": "integer","minimum": 18},
 "required": ["firstName", "lastName"]
}  

ii. XML(Extensible Markup Language)

XML is a text format derived from SGML. Like json, XML is both human and machine readable. Compared to JSON, XML is a lot more verbose. When XML is written with opening/closing tag pairs, the message body can be significantly larger than the comparable json message. Data in XML format is passed as strings, requiring metadata to describe fields and corresponding data types.

<xs:element name="user" type="lettertype"></xs:element>
<xs:complextype name="lettertype" mixed="true">
  <xs:sequence>
    <xs:element name="usertype" type="xs:string"></xs:element>
    <xs:element name="userage" type="xs:positiveInteger"></xs:element>
    <xs:element name="regdate" type="xs:date"></xs:element>
  </xs:sequence>
</xs:complextype>

So with the two, which one am I inclined to? well Simba….

3. API specification and styles

Having standard data API data formats reduces bikeshedding. However, even with these formats, API designs can get very diverse and different. Whereas this in not neccesarily bad where developers are free to create their own styles for their own convenience, it gets messy when bombarded with all sorts of sytles and sudo formats. However, there are a few defacto styles that have been adopted to standardize the different data formats. For XML, we have SOAP(Simple Object Access Protoco) architecture which is the most popular. For Json, the jury is still out with JSONAPI, JSend and OData JSON Protocol being strong contenders. JSONAPI has seen wider developer adoption, growth as well as community support, so very much inclined to it.

4. API Definition

API definition, similar to an API specification is a structured description of how the API behaves and what to expect from it in a human-readable format. It provides an indication of how the API is designed and the data types the API supports, without providing access to the source code. The only difference being API definition is meant for machine-consumption. It can be used to generate documentation, SDKs(Software Development Kits) and code samples. The most common API specification formats are Swagger/OpenAPI, RAML and API Blueprint.

i. RAML – RESTful Markup Language

RAML is an extension of the YAML specification for describing REST APIs The yml syntax is easy to read and write and is easily parsed to generate documentation. RAML is an end-to-end API tool providing for design, mocking, testing, documentation, and sharing.

ii. OpenAPI

Previously Swagger, the OpenAPI specification is arguably the most widely adopted specification format. The format is also based on YAML, making openapi specification documents easily readable. Swagger also provides tooling for the API lifecycle.

iii. API Blueprint

API Blueprint syntax is based on markdown, making it easily the most familiar for a developer.Most of the tooling provided around API blueprint is developed by the community.

5. API Documentation

The API documentation is a manual on how to use the API. It is meant for developers who want to take advantage of the api’s functions or services. There are many tools for auto-generating and maintaining API documentation. The generated documentation can either be static or interactive. Here’s a table of a few common ones and sample documentation for each.

6. API MOCKING.

Mocking refers to the process of simulating behavior. API mocking can, therefore, be described as the process of simulating the behavior of an API. Instead of using an actual API, a “replacement” is created. The “replacement” behaves like the original API, but lacks many of the functional and non-functional characteristics of the original component. Why mock an API? There are several scenarios where as a developer one might need to mock an API. Take the example of the development stage of a system we’ll call system Y. System Y might have external dependencies whose point of interaction is an API. The said system may not be available during development for security or other reasons. In such a case System Y’s developer might need to create a mock of the said dependancy’s API in order to proceed with the development process. For testing in cases where again the API is not available or for integration demonstration where exposing the actual API pose security risks. Most API tools such as SoapUI and Postman provide API mocking services along with other services to support the APIs lifecycle. There are, however, other tools both local and online that are dedicated to API mocking.

7. API TESTING.

API testing as defined by wikipedia is a type of software testing that involves testing application programming interfaces (APIs) directly and as part of integration testing to determine if they meet expectations for functionality, reliability, performance, and security.

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

This story was first published here: https://zegetech.com/blog/2018/12/08/api-dive.html 

Zege Technologies is a full-stack team of developers and designers based in Nairobi and working all over Africa. They use a state-of-the-art technology stack to build mobile and desktop web applications. 

Written by Melvin Otieno (Zege Technologies)