Fork me on GitHub

API Design

In the early days APIs were just about deploying and consuming. You were doing one or the other. Then came API management from providers like Mashery, then others like 3Scale and Apigee. Now the API universe is expanding and API design is coming front and center with new approaches, tools and even companies stepping up to provider services.

I define the world of API design as everything that goes into planning and designing your API, as well as the design of your API that lives on as your operational interface, and the truth in the contract you are entering into with API consumers.

Depending on our needs, API design may begin with learning about HATEOAS as part of your design definition or API design might be just about generating a Swagger definition so you can generate interactive API documentation, or possible automate your API monitoring and testing.

Ultimately your API design will be the definition of each endpoint, its methods, fields and much more. In a technical sense it is a JSON or XML blueprint that describes your API, and in a creative sense, API design is an art and can possess a strange technical beauty and speak to the value it delivers to end-users.

Thoughtful API design early on can save you a lot of mistakes down the road. This site is not meant to endorse any particular approach or methodology, but provide a single resource where you can find the best information on API design, allowing you to have a conversation around an API definition throughout its lifecycle.

This site will be an open source informational and technical repository of the companies, building blocks of API design, tools for assisting you in your API design planning and execution and companies that provide services in the area of API design.

My goal is to provide the information you need to navigate the world of API design. I’m also working on a white paper which will be published here when ready.


Updates

Messente API: Always Use A Backup DNS Solution

(Posted on )

I found the DNS implementation over at the Messente SMS API interesting, and worth of sharing for deeper evaluation. I've been considering the various approaches by API providers when crafting their domains, or subdomains for API access heavily over the last couple weeks. During some research time today I stumbled across the Messente SMS API which opts to provide two domains for making HTTP(S) requests of their API: api2.messente.com api3.messente.com Messente provides a little disclaimer to handle the developer side of manual load-balancing these API calls: These two domains have the same final destination regarding the API functions. In order......read more.



Establishing Common Dictionaries That Industries Can Use In Their API Design

(Posted on )

I’m going through each of the 100+ business sectors I track on as part of my API Stack. As I make my way through each sector, and generate Swagger, and APIs.json files, the language of the resources used across a particular sector starts to come into focus. I’m talking about the words used for crafting URLs, parameters, and the underlying data models for common APIs. In a perfect world everyone would come together and use something like Schema.org, and work to extend, in an organized, collaborative way across different industries—I would call this the Oxford English Dictionary (OED) approach. Unfortunately......read more.