API Providers Guide - API Design

Download as PDF

In the early days, APIs were just about deployment and consumption--you were doing one or the other.  Then from 2006 to 2012 API management was introduced from providers like Mashery, then 3Scale and most recently Apiphany. In 2013 the API universe is expanding at a ever increasing pace, and the concept of API design is expanding, with new approaches, tools and even companies stepping up to provide services.

I'm deciding to frame my API design research as everything that goes into planning and designing your API, as well as the resulting definition of your API, that will eventually become the  API you will use in production, which also might drive your documentation and generate the code samples your developers will use to integrate their apps.

Depending on our needs, API design may begin with learning about HATEOAS as part of your design constraints, or API design might simply be about generating a Swagger definition so you can generate interactive API documentation.

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 form and can possess a technical beauty, one that will also speak to the value an API delivers to end-users.

Thoughtful API design early on can save you a lot of mistakes down the road. In support of this, and as I do with al of my API research projects, I started a Github repository at design.apievangelist.com. This project 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. 

For those of you who like to share via email and PDFs, I also published the API Providers Guide to API Design as a PDF, which you can download and share as you wish.  

This API design project will be an open source repository containing the building blocks of API design, tools for assisting you in your API design, and companies that provide services in the area of API design.

This is a living project, that will be updated weekly. If you know of missing building blocks, or tools and services that should be included, or think I'm complete wacko, send your emails to [email protected] or tweet at me.