I am going through each of my research projects, and tightening things down, now that I have them all driven through my new, master stack of APIs. First up was API design, and the other day I spent time going through the organization I track on as part of my API design research, and today mission was to refine the tooling section.
Previously my tooling page was just an alphabetical list of tools, and I wanted to at least group things in a more meaningful way, reflecting how I break them down in my own monitoring system. So I reworked the publishing to allow me to group the tools by tags, resulting in the following list:
API Blueprint |
 API Blueprint
API Blueprint is a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown. API Blueprint is perfect for designing your Web API and its comprehensive documentation but also for quick prototyping and collaboration. It is easy to learn and even easier to read – after all it is just a form of plain text. API Blueprint, its parser, and most of its tools are completely open sourced so you don't have to worry about vendor lock-in. This also means you can freely integrate API Blueprint into any type of product, commercial or not.
|
|
|
 Atom Editor API Blueprint Preview
The Atom Editor API Blueprint preview is a plugin for the Atom editor that allows you to render HTML representation of API Blueprint in the right of the current open Atom editor using CTRL-SHIFT-A. This plugin requires Agilo to be installed and available in your path.
|
|
|
API Definitions |
| API Blueprint
API Blueprint is a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown. API Blueprint is perfect for designing your Web API and its comprehensive documentation but also for quick prototyping and collaboration. It is easy to learn and even easier to read – after all it is just a form of plain text. API Blueprint, its parser, and most of its tools are completely open sourced so you don't have to worry about vendor lock-in. This also means you can freely integrate API Blueprint into any type of product, commercial or not.
|
|
|
 RAML Specification
RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. The goal is to help our current API ecosystem by solving immediate problems and then encourage ever-better API patterns. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open spec.
|
|
|
 Swagger Specification
Swagger is a simple yet robust representation of a RESTful API, with a large ecosystem of API tooling that includes code generation, interactive documentation, and much more. Currently there are housands of developers supporting Swagger in almost every modern programming language and deployment environment, using the 100% open source software and specification.
|
|
|
API Design Editor |
| Atom Editor API Blueprint Preview
The Atom Editor API Blueprint preview is a plugin for the Atom editor that allows you to render HTML representation of API Blueprint in the right of the current open Atom editor using CTRL-SHIFT-A. This plugin requires Agilo to be installed and available in your path.
|
|
|
 Deployd
Deployd is the simplest way to build real-time APIs for web and mobile apps. Ready-made, configurable Resources add common functionality to a Deployd back-end, which can be further customized with JavaScript Events.
|
|
|
 RAML API Designer
API Designer is a standalone/embeddable editor for RAML (RESTful API Modeling Language) written in JavaScript using Angular.JS, which by default, uses an in-browser filesystem stored in HTML5 Localstorage. Mulesoft provides a cloud version of the editor as part of their larger API suite.
|
|
|
 Swagger Editor
Swagger Editor lets you edit API specifications in YAML inside your browser and to preview documentations in real time. Valid Swagger JSON descriptions can then be generated and used with the full Swagger tooling (code generation, documentation, etc).
|
|
|
API Design Guide |
 18F API Standards
18F is a technology team inside the US federal government. 18F is very API-focused: our first project was an API for business opportunities. This document captures 18F's view of API best practices and standards. We aim to incorporate as many of them as possible into our work. APIs, like other web applications, vary greatly in implementation and design, depending on the situation and the problem the application is solving.
|
|
|
 Heroku - API Design Guide
Heroku has provide their own set of what they call HTTP+JSON API design practices, which I think describes what we do much better than just web API. The guide is designed for internal and external usage, and looking to provide some consistency in API design, that anyone can follow.
|
|
|
 Paypal API Design Standards
Paypal has developed their own API design standards, providing a common blueprint for their teams to follow, while also transparently sharing with their API community, and the wider API industry to follow.
|
|
|
 Realtime API Design Guide from Fanout
An API Design Guide dedicated to helping you understand the common design approaches, as well as the pros and cons of realtime API design, showcasing the implementations of 16 public real-time APIs--developed by Fanout.io
|
|
|
 The RESTed NARWHL
NARWHL is a framework intended to provide a roadmap for those needing to implement an API using current best practices but flexible enough to grow into the future. This guide contains a set of API design recommendations you can implement today with the confidence that your API will be RESTful (level 3 according to the Richardson Maturity Model) and able to adapt to future iterations while still making it easier for developers to use.
|
|
|
 UK Government Service Design Manual for APIs
Martha Lane Fox report called for government to act as a wholesaler, as well as the retail shop front, for services and content by mandating the development and opening up of Application Programme Interfaces (APIs) to third parties -- this section is a set of guiding principles for exposing a digital service as an API.
|
|
|
 White House Web API Standards
This document provides guidelines and examples for White House Web APIs, encouraging consistency, maintainability, and best practices across applications. White House APIs aim to balance a truly RESTful API interface with a positive developer experience (DX).
|
|
|
RAML |
| RAML Specification
RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. The goal is to help our current API ecosystem by solving immediate problems and then encourage ever-better API patterns. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open spec.
|
|
|
Swagger |
| Swagger Specification
Swagger is a simple yet robust representation of a RESTful API, with a large ecosystem of API tooling that includes code generation, interactive documentation, and much more. Currently there are thousands of developers supporting Swagger in almost every modern programming language and deployment environment, using the 100% open source software and specification.
|
|
|
I have other resources I need to add to this list, but each one requires a certain amount of love before its ready to be included. Everything here should be openly licensed, providing essential tools API providers, designers, and architects will need. If there is something that you think should be here, let me know, and I will consider adding it.
One area I am still working on, is cross linking areas of tooling, potentially with other research areas. For example API definitions has its own evolving area, and Swagger does as well. This is why I wanted to retool and break things down by tags, because some of these tags eventually become other projects, and when I break off a new area, I want to keep things connected.
Next I'll give the API design building blocks page a little attention, but it was recently overhauled, so I think I am pretty good there. After that, I need to give my paper API a little love, which allows me to aggregate my design research into a white paper. Once I'm done with that I'll quickly go through some of my other core research like API deployment, management, discovery, and beyond.
