Overview of The API Design Space
In the early days of APIs, everything was just about deploying and consuming—you were doing one or the other. Then by 2006 we saw the stabilization of common API management practices emerge from providers like Mashery, and then 3Scale. Now in 2014 we are stabilizing again, and the API universe is expanding around the area of API design, with new approaches, tools and entire companies emerging to provide services that are dedicated to helping companies design the best APIs they can.
I define the world of API design as everything that goes into planning and designing your API, as well as the definition of your API that will eventually be deployed as your production endpoints, drive your documentation, generate the code samples your developers will use to integrate, test, monitor, and allow your API to be found--through this lens, API design is fast becoming the driver for all areas of the API lifecycle.
Depending on our needs, API design may begin with understanding HTTP, and REST, or may learning more about applying hypermedia as part of your design constraints, or API design might simply be about generating a Swagger definition, so you can generate interactive API documentation. I won’t be going into the finer points of REST, Hypermedia or even Swagger definitions. My goal is to provide a 100K view of space, and highlight the various tools, services, and API design methodologies available today.
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, YAML or markdown blueprint that describes your API, and in a creative sense, API design is an art that can possess a strange technical beauty, and speak to the value an API delivers to end-users. API design is far more than just how you structure URIs, or parameters, it is fast becoming a discipline, with a suite of services and tools to support a growing wave of API design professionals.
Thoughtful API design early on can save you a lot of mistakes down the road. 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, and go there to find what you need. It can be difficult to stay up with the latest tools, and approaches, and API Evangelist looks to fill this gap.
This API design project will live as an open source repository, and resulting white paper containing the building blocks of API design, tools that assist 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 as I have time.. If you know of missing building blocks, or tools and services that should be included, send them to [email protected]
