{"API Evangelist"}

The API Design Tooling I Have Included In My Research

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.