Overview of designing APIs?

In an integration scenario, API (Application Programmable Interface) is used by a service provider to represent a function that consumers can use. Consumers would ideally like a stable and simple to consume API. This requires that the API details are appropriately documented by the API provider. These details should allow users and machines to discover and understand capabilities of the service with close-to no access to source code and implementation details.

Aim of designing APIs is to address this concern by providing a specification to present APIs in a standard, language agnostic format. There are multiple competing specification/standards working in this space:

1. Swagger
2. RAML RESTful API Modeling Language
3. Apiary
4. API Blueprint

Swagger is getting a fair bit of traction in the market and has donated their specification to Open API Initiative. I will be using Swagger as a reference implementation when discussing API modeling/designing.

It is worth highlighting that modeling or designing of APIs assists with governance during design (including development) time only.
Runtime governance is implemented by API Management solutions like APIMan.

Common patterns with API design

1. Top-down approach

In a top-down approach, API designer would use an editor like Swagger Editor to create an API definition. Using this definition, a developer can then use code generation tools to generate a stub for server side implementation.

API definitions could also be created using a simple text editor.

2. Bottom-up approach

In a bottom-up approach, an implementation of API already exists. A user can then either create the definition manually or in certain cases (if appropriate frameworks like JAX-RS) API definition can be generated automatically.

3. Consuming a well designed API

Using an API definition, a consumer can explore the API and generate client library.

What about WADL?

WADL (Web Application Description Language) is a machine readable description of HTTP-based web applications like REST web services. Writing a WADL manually is an extremely tedious task.