API StylebookDevelop your own API design style guide for your company based upon the approach of the leading API providers.

The API Stylebook is a forkable collection of the top API design guides from leading API providers. Providing a blueprint that anyone can follow when planning and designing their APIs.

The web is based on a large and growing set of open and shared specifications —providing a wealth of proven formats for use when delive-ring APIs on the web.

Erik Wilde has put together, and is actively maintaing the easy to navigate and ready to go collection of essential web concpets that should be influencing your design today.

Vers ion 2017.09 API Design Patterns, Services, and Tooling From Across The Space

Web Concepts

{“API”:“Design”}

API Definition2

01 02 03API Stylebook Webconcepts.info

Develop your own API design style guide for your company based upon the existing approach of leading API providers.

The API Stylebook is a forkable collection of the top API design guides from leading API provi-ders. Providing a blueprint that anyone can follow when desig-ning their APIs.

RESTful APIs dominate, but hypermedia, raphQL, and gRPC are on the rise. API design clearly is not just a dis-cussion about REST anymore.

I wanted to take a moment and look at what a diverse API design toolbox looks like in 2017, and understand the dominant approaches being applied.

The web is based on a large and growing set of open and shared specifications —providing a wealth of proven formats for use when delivering APIs on the web.

Erik Wilde has put together, and is actively maintaing the easy to navigate and ready to go collec-tion of essential web concpets that should be influencing your design.

Table of Contents

WRITTEN BY: Kin Lane WRITTEN BY: Kin Lane WRITTEN BY: Kin Lane

A Diverse API Toolbox

INDEX SEC TION

{“API”:”Design”}

API Definition 3

04 05 06Building Blocks Services Tooling

EDTR

L API Design is an API Evangelist production, operated by Kin Lane. It is a solo

effort from someone who has been monitoring the technology, business, and

politics of APIs since 2010.

This guide is designed to be a summary of the world of API design, providing

the reader with a recent snapshot of the variety of approaches, services, and

tooling that is available out there to help API designers, developers, and archi-

tects deliver more consistent and effective APIs as part of their operations.

API Definition4

API Design

I ndustr y Guide

Design is about pausing and thoughtfully approaching API development.

API Definition 5

Around 2012 API development started becoming more than just about writing code, and began to focus on the finer details of defining exactly the interface that is needed to get the job done.

API design is the thought and practice that goes into the digital resources we are making available via the modern internet. De-

pending on what technical or business discipline you come from, API design is going to mean different things to you. To many,

API design means REST, a set of principles for delivering APIs using the web. To others, it will mean hypermedia, GraphQL, or

maybe RPC. API design is about considering a variety of architectural patterns and working with key stakeholders to establish

common set of API design guidelines that leverage best practices of the API community at large.

REST is widely considered to be the dominant API philosophy. Newcomers to the space should begin their journey here,.

learning the inner workings of HTTP and exploring the modern means of distribution of data, content, and other resources.

This guide focuses heavily on showcasing the common building blocks of RESTful API design, as well as some of the supporting

tools and services. It also provides a timely overview of other leading design patterns to share what is happening in the real

world of APIs.

There are many effective examples of RESTful API design patterns, even whole books dedicated to API design. My intent is to

illuminate some of these existing methods, while painting a larger picture of what API design is, beyond any single methodolo-

gy or vendor I’m simply studying what is already happening, educating myself about API design practices, and forming my own

opinions about what is best across a variety of different scenarios, which is something you should be doing in your own way to

meet your API design objectives.

Like other areas of design, simplicity rules. It is tempting to deliver highly engineered and versatile APIs that do a lot. But,-

the best known (and most used) APIs often do one thing and do it very well. Simplicity stands out in the API space. The most

effective APIs are simple, intuitive, and useful. The more you invest in the design of your API, the less you will have to spend

educating and onboarding consumers of your APIs.

RESTful API design patterns are where you should be starting your API journey. You should also educate yourself about hyper-

media and GraphQL. There are also streaming and gRPC API patterns designed for higher volume, always on resources. Spend

time getting to know the API landscape you are looking to operate in and study the API design patterns used by the competi-

tion and leaders in your intended space.

The latest API design discussions often center around the usage of machine readable API specifications like OpenAPI, API

Blueprint, and RAML. These specifications provide a shareable definition that can establish an understanding across team

members and project stakeholders, while also providing a machine readable definition that can be used in documentation, and

other systems, and client tooling. API specifications are central to the API design process. The resulting definition acts as a

contract throughout the technical, business, and legal side of API operations.

WRITTEN BY: KIN LANE

API Definition6

API Stylebook

Arnaud Lauret (@arno_di_loreto), the API Handyman (@

apihandyman), has been developing an API Stylebook that

provides a collection of resources for API designers. It is

a brilliant aggregation of thirteen API design guides from

Atlassian, Cisco, Cloud Foundry, Google, Haufe, Heroku,

Microsoft, PayPal, Red Hat, The White House, and Zalando. It

highlights best practices used by leading API providers.

“The API Stylebook aims to help API Designers to solve

API design matters and build their API design guidelines by

providing quick and easy access to selected and categorized

resources”, says Lauret. A unique community resource, it pro-

vides deep linking to specific topics within publicly available

API design guidelines. Instead of reinventing the wheel or

searching Google for hours, API designers quickly can find

solutions and inspiration from these existing best practices.

More than just a list of guidelines, it is a machine readable

distillation of the thirteen API design guides into a master

list of API design topics you can consider when crafting your

own API design guide. It is slick. I like Arnaud’s approach to

analyzing the existing API design patterns across the API

platforms who have shared their guides. I also really like the

YAML approach and it’s presented as a very good looking

website using Github, and Github Pages.

This is how API literacy tools should be constructed and it

provides a valuable lesson in API design. You can take that

Build an API design style guide for your company based upon the existing approach of leading API providers.

WRITTEN BY: KIN LANE

01

REST is not a standard, i t is a phi-losophy . It is learned from other pract it ioners in the API space.

API Definition 7

The API Stylebook is a forkable set of best practices when it comes to API design in 2017

lesson and execute what you’ve learned along the way, with

a very hands-on process. Using the API Stylebook, you can

craft an API design guide for your team to follow and employ

across API operations. Anyone can fork the API Stylebook,

pick and choose the best practices across the thirteen API

design guides, and then publish a version as a Github repo-

sitory. The resulting repo can easily be included in your API

docs, as a standalone website.

There are two things going on here. First, API providers are

sharing their views on API design best practices — important

stuff. Second, an aggregator (API Handyman) makes these

best practices machine-readable, forkable, and reusable. This

knowledge layer of API operations becomes even more va-

luable when it is openly accessible and shareable in this way.

We need our APIs to employ common patterns and speak in

common formats so that they’ll work together and reduce

friction in the industries where they being put to work. API

Stylebook approaches API design through continuous inte-

gration, allowing API development groups to define API me-

thodologies that can be deeply integrated into our lifecycle.

The more API design guides that are sourced in the API

Stylebook, the better the available topics will become.

Arnaud will be adding new API design guide to the stack. It

is better for the community if you start with his existing list

of topics and add your own YAML definitions that drive the

API Stylebook on Github, but we’ll take what we can get. It is

a process that every company, organization, institution and

government agency should go through and what you learn

along the way is essential for any API team.

API design isn’t just knowing the details of REST or any single

architecture pattern. It’s the knowledge you gain from the

definition process, and a huge part of this process is having

an effective pool of community knowledge to pull from.

Arnaud has done an amazing job at processing disparate and

unstructured API design and yielding coherent list of topics

that we can all consider in our own API design process. We

should all be investing in (and building on) his work.It is

something I’m baking into my API design research wherever I

can — dovetailing the common building blocks I’ve aggregate

across his very detailed work.

REST is a philosphy, not a standard. The current wave of web

API success we see across the technology landscape has

been about API providers building on top of the best practi-

ces of the web API providers that came before them, going

back to the early pioneers of SalesForce, eBay, and Amazon.

Every API architect I know has learned from reverse engin-

nering and studying the practices of what they’d consider

to be well designed APIs, and understanding the bad design

practices out there. If knowledge isn’t shared, then the next

generation of API developers do not learn from what came

before them. Making the practice of publishing your API

design guide for your API not just good for your own API

operations, but good for the entire API community.

The most significant API movements in the last five years

came from Apiary in my opinion, but the most significant API

movements in the next five years will be about sharing API

design patterns on Github. Allowing API providers to borrow

from each other, resuse, and communicate around common

API patterns that are working, or not working. API definitions

are allowing us to publish these common design patterns to

Github, and the next generation of continous integration and

deployment tooling like API Stylebook allow us to publish,

share, and even test the quality of our APIs.

I will be continuing to invest in API Stylebook, writing stories

about it, and helping API providers understand the value of

the open source project and sharing of their own API design

patterns, and since it’s machine readable, I will be integrating

the API Stylebook into all of my API design research.

API Definition8

WebConcepts.info

Keeping up with the standards bodies like International

Organization for Standardization (ISO) and Internet Enginee-

ring Task Force (IETF) can be a full time job. Thankfully, Erik

Wilde (@dret) has help simply and made the concepts and

specifications that make the web work more accessible and

easier to understand, with his WebConcepts.info project.

According to Erik, “the Web’s Uniform Interface is based on a

large and growing set of specifications. These specifications

establish the shared concepts that providers and consumers

of Web services can rely on. Web Concepts is providing an

overview of these concepts and of the specifications defi-

ning them.” His work is a natural fit for what I am trying to

accomplish with my API definition industry guide, as well as

supporting other areas of my research.

One of the areas that slows API adoption is a lack of awar-

ness of the concepts and specifications that make the web

work among developers who are providing and consuming

APIs. The modern API leverages the same technology that

drives the web--this is why it is working so well. The web is

delivering HTML for humans, and APIs are using the same

to deliver machine readable data, content, and access to

algorithms online. If a developer is not famiilar with the fun-

damental building blocks of the web, the APIs they provide,

and the applications they build on top of APIs will always be

deficient.

The Web’s Uniform Interface is based on a large & growing set of specifi-cations--establishing a shared concepts across providers & consumers.

Web Concepts helps soften, and make these critical

concepts and specifications accessible and digestible

for a new generation of web and API developers.

WRITTEN BY: KIN LANE

03

API Definition 9

Many API architects are deficient in an awareness of the

concepts and specifications that make the web work.

This project provides an overview of 28 web concepts with

643 distinct implementations aggregated across five separa-

te organizations including the International Organization for

Standardization (ISO), Internet Engineering Task Force (IETF),

Java Community Process (JCP), Organization for the Advan-

cement of Structured Information Standards (OASIS), and

the World Wide Web Consortium (W3C)--who all contribute

to what we know as the web. An awareness and literacy

around the 28 concepts aggregated by Web Concepts is

essential for any API developer and architect looking to fully

leverage the power of the web as part of their API work.

After aggregating the 28 web concepts from the five stan-

dards organization, Web Concepts additionally aggregates

218 actual specifications that API developers, architects, and

consumers should be considering when putting APIs to work.

Some of these specifications are included as part of this API

Definition guide, and I will be working to add additional spe-

cifications in future editions of this guide, as it makes sense.

The goal of this guide is to help bring awareness, literacy, and

proficiency with common API and data patterns, making use

of the work Web Concepts project, and building on the web

literacy work already delivered by Erik, just makes sense.

Web Concepts is published as a Github repository, levera-

ging Github Pages for the website. He has worked hard to

make the concepts and specification available as JSON feeds,

providing a machine-readable feed that can be integrated

into existing API design, deployment, and management appli-

cations--providing web literacy concepts and specifications

throughout the API life cycle. All JSON data is generated

from the source data, which is managed as a set of XML des-

criptions of specifications, with the build process based upon

XSLT and Jekyll, providing multiple ways to approach all con-

cepts and specifications, while maintaining the relationship

and structure of all the moving parts that make up the web.

When it comes to the startup space, the concepts that make

up the web, and the specifications that make it all work,

might seem a little boring, something only the older engi-

neers pay attention to. Web Concepts helps soften, and

make these critical concepts and specifications accessible

and digestible for a new generation of web and API develo-

pers--think of them as gummy versions of vitamins. If we are

going to standardize how APIs are designed, deployed, and

managed--making all of this much more usable, scalable, and

interoperable, we are going to have to all get on the same

page (aka the web).

Web Concepts is an open source project, and Erik encoura-

ges feedback on the concepts, and specifications. I encou-

rage you to spend time on the site regularly, and see where

you can integrate the JSON feeds into your systems, servi-

ces, and tooling. We have a lot of work ahead of us to make

sure the next generation of programmers have the base

amount of web literacy necessary to keep the web strong

and healthy. There are two main ways to contribute to the

building blocks of the web: participate as a contributor to the

standards body, or you can make sure you are implementing

common concepts and specifications throughout your work,

contributing to the web, and not just walled gardens and

closed platforms.

API Definition10

Use The Web Simplicity Consistency

Seek simplicity at every turn when designing APIs, providing the smallest possible unit of value you possibly can. At every turn, think about how you can keep things precise, doing so-mething very well, rather than letting things grow out of control, increasing in complexity with each iteration and version of your API.

The web brings a number of open standards and protocols to the table. Make sure to learn about existing standards and put them to use across your API design process. APIs are the next evolutionary step of the web, and you need to make sure you are building on what is already there, and not reinventing the wheel.

Employ consistent approaches to all aspects of API design. Provide-consistency for humans, but also for machines, so they can grok what an API does as easily. A good REST URI can look something like /resources/id/sub-resources/id. Providing a consistent framework for each available resource.

API Academy

The API Academy team consists of industry experts who have been brought

together by CA Technologies to provide expert consulting services for organi-

zations that want to take their API programs to the next level.

URL: http://apis.how/api-academy

Building Blocks - Best Practices

Easy to Learn Hard To Abuse Handle Change

When an API does one thing and does it well, you reduce the opportunity for misuse. Always consider what someo-ne can do with your API to hurt your organization, or possibly someone else. Wen designing your API think about misuse, and try to think out of the box, and think deeply about how your API will be viewed externally.

Keep APIs simple and consistent so they are easy to learn by any potential API consumer. Your API should be intuitive, using plain dictionary titles, descriptions, and other elements. API documentation is required for all APIs, but the overall design of your API should speak volumes about what is possible with an API.

Change is inevitable. Handling it is a big part of a successful API design strategy. The decision you make here will persist throughout the life of an API. When crafting the design of your APIs, think deeply about what the future will hold, and how each change will impact your API consumers.

A common set of best practices have emerged as part of web API operations, who enjoy a significant amount of adoption.

04

API Definition 11

Building Blocks - HTTP Methods

GET POST PUT

The POST method requests that the server accepts the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.

The GET method requests a repre-sentation of the specified resour-ce. Requests using GET should only retrieve data and should have no other effect. GET is the most common aspect of using the web, something everyone does on a daily basis

The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.

Verbs Are The Engine Of Your API Design

HTTP Verbs are the actions behind your API design. Every path you craft

will have these verbs behind the words you choose, HTTP is the vehicle for

enabling the trasnport of valuable data, content, and algorithms, and the

HTTP verbs allow you to articulate the action behind any of these API enabled

occurrences.

PATCH DELETE OPTIONS

The DELETE method deletes the specified resource. This method MAY be overridden by human intervention (or other means) on the origin server.

The PATCH method applies partial modifications to a resource. The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-

The OPTIONS method returns the HTTP methods that the server supports for the specified URL. This can be used to check the functionality of a web server by requesting ‘*’ instead of a specific resource.

The HTTP protocol comes with a set of common verbs that can be applied to noun-based resources available via APIs.

04

API Definition12

Keeping Things Simple And Intuitive

Any request made of an API should be simple, intuitive, and fulfilling a specific

need. The surface area of an API will refelect the requests we make of many

websites and applications, but APIs will be tailored for a wider set of uses,

including mobile, messaging, voice, and other emerging applications.

There are never any perfect answers when it comes to API design request, but

keeping things simple, thoughtful, and precise will always apply.

Building Blocks - API Requests04

Encryption Host Path

Provide a clear, intuitive domain or subdomain dedicated to API traffic for use as the base url for all API requests.

Consider enabling encryption by for all API paths, thus properly securing all requests in transit.

Craft simple, expressive, and mea-ningful paths for API requests that direct consumers to the resources they need.

Parameters Headers Body

Augment request parameters. HTTP headers provide an added layer for defining the request and provide a secure way to transmit sensitive items like tokens.

Offer a wealth of parameters that define the surface area of any API re-quests, leading to exactly the response needed.

A body can be used to transmit data, and content as part of each API request. It’s not used for GET or DELETE actions.

API integration always begins with a request to a specific domain and the path to the desired resource. Here are the key elements you should be thinking about with each API.

Filtering Sorting Pagination

Establish a single approach to how API responses will be returned and implement consistently across all available API resources. Putting con-trol in consumers hands, or not.

Consider both headers and parameters in the service of filtering API requests There are many different approaches avilable for filtering data and API schema.

Define common pagination across large volumes of data, set with parameters, headers, or as part of the request body. Consider other hypermedia meda types here.

API Definition 13

Building Blocks - API Responses

Headers Status Codes Error Handling

Humans won’t be there to always understand the nature of a res-ponse, the HTTP status codes is

As with requests, making sure re-levant headers are present as part of each API response, defining the

Establish a single error handling strategy, and apply consistently across all API operations.

W3C

The World Wide Web Consortium (W3C) is an international community where

Member organizations, a full-time staff, and the public work together to de-

velop Web standards. Led by Web inventor Tim Berners-Lee and CEO Jeffrey

Jaffe, W3C’s mission is to lead the Web to its full potential.

UR: URL: http://apis.how/w3c

CORS Request-Ids Collections

Provide request-Ids, if possible, for added details for logging, audi-ting, and reporting on API usage. Provides a framework for uniquely identifying API responses.

A common way to lock down web-sites, cross-origin HTTP request should be enabled to allow for the widest possible access without limitations.

Instead of a single object, consider returning and defining collections. Also consider hypermedia, and other common media types that help with organizing responses.

Carefully considering each details of API responses, while leveraging the common building blocks of the web to ensure API responses are consistent, and reliable.

04

Caching eTags HTML Encoding

Provide eTags as part of caching operations to improve the effi-ciency of API responses

Well implemented caching can improve security and help with redundancy, as well as speed up performance

Provide a defined character encoding, which for many of my readers should be UTF-8.

API Definition14

Make Sure You Define What Success Means

It can be easy to just default to 200 OK for all responses. Many APIs I come

across have two status codes: 200 and 500. Do not just response with suc-

cess by default. Make sure you take the time to define what success is, and

realize that things aren’t always 200K

Building Blocks - HTTP Status Success

04

200 OK 201 Created 202 Accepted

The request has been fulfilled, resul-ting in the creation of a new resource.

Standard response for successful HTTP requests, delivering what was requested.

The request has been accepted for processing, but the processing has not been completed.

204 No Content 205 Reset Content 206 Partial Content

The server has fulfilled the request and desires that the user agent reset the document view.

The server successfully processed the request and is not returning any content.

The server is delivering only part of the resource (byte serving) due to a range header sent by the client.

HTTP status codes are used when an API request is success-ful, providing the desired response an API consumer is loo-king for.

207 Multi-Status

Providing status for multiple indepen-dent operations in a single response.

API Definition 15

Building Blocks - HTTP Status Redirection

301 Moved Permanently 302 Found 303 See Other

The target resource resides tem-porarily under a different URI.

This and all future requests should be directed to the given URI.

The response to the request can be found under another URI using a GET method.

Think About Linkrot

Evaluate linkrot, and learn from the mistakes we are making with the web.

APIs do not have to stick around forever, but they should communicate with

clients when things change, helping connect the dots between ever changing

resources are managing each day.

http://apis.how/link-rot/

304 Not Modified

Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match.

Things change on the web and API requests need to respond accordingly so that clients can adjust based upon things mo-ving or going away.

04

API Definition16

Building Blocks - HTTP Status User Error

04

400 Bad Request 401 Unauthorized 402 Payment Required

Similar to 403 Forbidden, but speci-fically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge.

The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, too large size, invalid request message framing, or deceptive request routing).

Payment is required for using resource -- not implemented, for future use.

403 Forbidden 404 Not Found 405 Method Not Allowed

The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.

The request was a valid request, but the server is refusing to respond to it. The user might be logged in but does not have the necessary permissions

A request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presen-

400 series HTTP status codes help the client understand when an error has been caused by something a user or the application has caused.

406 Not Acceptable

The requested resource is capable of generating only content not accepta-ble according to the Accept headers sent in the request.

408 Request Timeout

The server timed out waiting for the request. According to HTTP specifi-cations: The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifica-

409 Conflict

Indicates that the request could not be processed because of conflict in the request, such as an edit conflict be-tween multiple simultaneous updates.

Give Me More Than Just Not Found

There are many different reasons for why a digital resource is not found.

Similar to thinking about what success means, think about the impact of

something not being found. It should never be 404, oh well. 400 series errors

should tell you a lot about the overall health of your API infrastructure.

API Definition 17

Building Blocks - HTTP Status User Error

Close Your Eyes To See The Importance Of HTTP Status Codes

Similar to link relations and other building blocks of web APIs I often close my

eyes to understand the importance of HTTP Status Codes. How will external

systems, and applications truly understand the response any API gives. If your

API doesn’t return an informative HTTP Status Code, nobody will ever truly

understand what an API response truly means.

400 series HTTP status codes help the client understand when an error has been caused by something a user or the application has caused.

04

410 Gone

Indicates that the resource requested is no longer available and will not be available again. This should be used when a resource has been intentiona-lly removed and the resource should be purged.

411 Length Required

The request did not specify the length of its content, which is required by the requested resource.

412 Precondition Failed

The server does not meet one of the preconditions that the requester put on the request.

415 Unsupported Media Type

The request entity has a media type which the server or resource does not support.

422 Unprocessable Entity

The request was well-formed but was unable to be followed due to semantic errors.

423 Locked

The resource that is being accessed is locked.

428 Precondition Required

The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.

429 Too Many Requests

The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.

API Definition18

Building Blocks - HTTP Status Server Error

04

500 Internal Server Error 501 Not Implemented 503 Service Unavailable

The server either does not recognize the request method, or it lacks the abi-lity to fulfill the request. Usually this implies future availability (e.g., a new feature of a web-service API).

A generic error message, given when an unexpected condition was encoun-tered and no more specific message is suitable.

The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

HTTP status codes are used when an API request is successful, providing the desired response an API consumer is looking for.

API Stability

One of the reasons I have dedicated such a significant portion of this API

design industry guide to HTTP Status Codes is that they are important not just

the stability and reliability of a single API, they are essential to this whole API

thing working at scale. We need stable and reliable resources for our applica-

tions, to depend on, which all communicate effecively about what is working,

as well as what is not working.

API Definition 19

In the last five years, a handful of new specification formats have emerged,

allowing us to better describe what application programming interfaces (API) do,

and how they can be put to work across the software development life cycle. The-

se new API definition formats allow for the location, response, requests, and other

essential technical, business, and legal aspects of what an API does to be described

in a human readable (YAML), but also machine-readable (JSON) way -- fueling new

ways to think about digital automation on the web.

In 2012, it was common for API definitions to be developed to assist in the

generation and maintenance of API documentation--keeping the programmatic

interface in sync with the human (consumer) interface. As the API sector continued

to evolve, these same API definitions started to become applied as part of the API

design process, allowing key technical and business stakeholders to communicate

around the design of the API, even before any code was written, and documenta-

tion was even needed. This changed how we develop APIs, allowing stakeholders

to be involved much earlier on in the development process, and saving valuable

development cycles.

In 2016, these API definitions are being used to design, mock, deploy, document,

manage, test, generate SDKs, and numerous others stops along the API life cycle.

Additionally, evolution in defining the underlying data model used in API requests

and responses have also been pushed forward, further refining how we define and

communicate about OAuth scopes that govern identity and access to APIs, and the

valuable data, content, and algorithms they expose.

API definitions allow us to have a conversation about API design. Many folks see

OpenAPI, API Blueprint, and other API definition formats all about delivering

documentation, or generation code. API definitions give us the parts and pieces, as

well as the scaffolding we need to have an organized, structured conversation. My

API definition research and this API design research are connected at the hip--one

doesn’t exist without the other.

Definitions are used at every stop along the API life cycle

today.

API Definitions & API Design

API definitions, schema, and scopes are playing a central role across every industry -- providing a common language that can be used across web, mobile, device, and other applications.

API Definition20

text/html application/xml application/atom+xml

Provide XML media types for API requests and responses.

Provide HTML media types for API requests and responses.

Provide ATOM media types for API requests and responses.

The Internet Assigned Numbers Authority (IANA) is a department of ICANN,

a nonprofit private American corporation that oversees global IP address allo-

cation, autonomous system number allocation, root zone management in the

Domain Name System (DNS), media types, and other Internet Protocol-related

symbols and Internet numbers.

Common Media Types

application/json application/csv text/tab-separated-values

Provide comma separate value (CSV) media types for API re-quests and responses.

Provide JSON media types for API requests and responses.

The commonly used API media types as defined by IANA, provi-ding a base set of content types that all APIs should be serving up.

04

Provide tab separated values (TSV) media types for API re-quests and responses.

iana

APIs should offer a range of media types allowing consumers to negotia-te the best content type for their needs

URL: http://apis.how/iana/

API Definition 21

Hypermedia Media Types

JSON API Collection+JSON Siren

Collection+JSON is a JSON-based read/write hypermedia-type desig-ned to support management and querying of simple collections.

JSON API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.

Siren is a hypermedia specification for representing entities. As HTML is used for visually representing documents on a Web site, Siren is a specification for presenting entities via a Web API.

URL: http://apis.how/coll-json/URL: http://apis.how/json-api/ URL: http://apis.how/siren/

JSON-LD Hypertext Application Language (HAL)

Mason

HAL is a simple format that gives a consistent and easy way to hyper-link between resources in your API.

JSON-LD, or JavaScript Object No-tation for Linked Data, is a method of encoding Linked Data using JSON. It was a goal to require as little effort as possible from deve-lopers to transform their existing JSON to JSON-LD.

Mason is a JSON format for intro-ducing hypermedia elements to classic JSON data representations.

URL: http://apis.how/hal/URL: http://apis.how/json-ld/ URL: http://apis.how/mason/

The leading hypermedia formats being applied during the API de-sign process providing a much more rich API integration experience.

04

URL: http://apis.how/foxy-api/

The Foxy Hypermedia API is designed to give you complete control over all

aspects of your Foxy accounts, whether working with a single store or auto-

mating the provisioning of thousands. Anything you can do within the Foxy

administration, you can also do through the API.

Foxy.io

API Definition22

OpenAPI Specification API Blueprint RAML

API Blueprint is a documenta-tion-oriented API description langua-ge that makes semantic assumptions over just having plain Markdown. API Blueprint is perfect for designing your Web API and its comprehensive docu-mentation but also for quick prototy-ping and collaboration.

The goal of The OpenAPI Specification is to define a standard, language-ag-nostic interface to REST APIs that allows both humans and computers to discover and understand the capabi-lities of the service without access to source code, documentation, or throu-gh network traffic inspection.

RESTful API Modeling Language (RAML) is a simple and succinct way of describing practica-lly-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices.

URL: http://apis.how/api-blueprint/URL: http://apis.how/openapi-spec/ URL: http://apis.how/raml/

The Open API Initiative (OAI) was created by a consortium of forward-looking

industry experts who recognize the immense value of standardizing on how

REST APIs are described. As an open governance structure under the Linux

Foundation, the OAI is focused on creating, evolving and promoting a vendor

neutral description format. While the initiative focuses on the OpenAPI Speci-

fication, other format providers like Apiary are also part of the iniative opening

up the potential for the effort to impact beyond just a single API definition.

API Specifications

Postman Collection RESTful API Description Language (RADL)

RESTful Service Descrip-tion Language (RSDL)

RESTful API Description Language (RADL) is an XML vocabulary for des-cribing Hypermedia-driven RESTful APIs. Unlike most HTTP API descrip-tion languages, RADL focuses on defi-ning a truly hypermedia-driven REST API from the clients point of view, moving the conversation forward.

A collection groups individual re-quests together, allowing them be organized into folders, accurately mirrorring your API. Requests can also store sample responses when saved in a collection. You can add metadata like name & description too so that all the information that a developer needs to use your API is available.

The RESTful Service Description Language (RSDL) is a machi-ne- and human-readable XML description of HTTP-based web applications (typically REST web services), adding another way to describe APIs in a machine reada-ble format.

URL: http://apis.how/radl/URL: http://apis.how/pstmn-col/ URL: http://apis.how/rsdl/

The leading specification formats for describing the response, request & security model of web APIs--defining what it does.

04

API Definition 23

Data Schema

JSON Schema Application-Level Profile Semantics (ALPS)

Asset Description Metada-ta Schema (ADMS)

A data format for defining appli-cation-level semantics, similar to HTML microformats. ALPS can be used as a profile to explain the application semantics agnostic media types.

Describes your JSON data format in clear, human- and machi-ne-readable documentation that is complete structural validation, useful for automated testing, and validating client-submitted data.

ADMS is a profile of DCAT used to describe semantic assets as highly reusable metadata (e.g. xml schemata, generic data models) and reference data (e.g. code lists, taxonomies, dictionaries, vocabu-laries) for system development.

URL: http://apis.how/alps/URL: http://apis.how/json-schema/ URL: http://apis.how/adms/

Schema.org

Schema.org is a collaborative, community activity with a mission to create,

maintain, and promote schemas for structured data on the Internet, on web

pages, in email messages, and beyond. Schema.org vocabulary can be used

with many different encodings, including RDFa, Microdata and JSON-LD.

URL: http://api.how/schema-org/

Markdown Syntax for Ob-ject Notation (MSON)

Open Data Protocol (ODa-ta)

Docson

OData is an OASIS standard defi-ning the best practice for building & consuming RESTful APIs, hel-ping you focus on your business logic while building RESTful APIs without having to worry about de-fining request & response headers.

MSON is a plain-text, human and machine readable, description for-mat for describing data structures in common markup formats such as JSON, XML or YAML.

Docson is a data schema format that delivers JSON types using JSON schema, allowing you to define the undlerying data defini-tion in the service of publishing beautiful documentation.

URL: http://apis.how/odata/URL: http://apis.how/mson/ URL: http://apis.how/docson/

Formats for defining data schema, fields, default values, and other elements for use in all API requests & responses.

04

API Definition24

Current API design focusses on using schema to help quantify the payload of the

request and response structure of our APIs. JSON Schema, MSON, and other data

specifications have emerged to help us quantify the bits we are passing back and

forth with APIs. Alongside this evolution, another data format has emerged to help

us define simple descriptions of our application-level semantics, similar to how we

are using HTML microformats to share data on the web, Application-Level Profile

Semantics (ALPS).

ALPS goes well beyond schema, which provides a representation of a plan or

theory in the form of an outline or model. ALPS provides a way to define the mea-

ning behind the data, content, and other resources you are making available via an

API. ALPS seeks to establish a shared understanding by illuminating the meaning

behind hypermedia interfaces (data and state transitions) such as HTML, Collec-

tion+JSON, HAL or Siren. It encourages reusability of common profile documents

across the media types we are depending on.

Using ALPS you can easily define the common data elements we all use in our API

like contacts, todo lists. It can even describe the structure of our APIS for verbose

and more useful error responses. What really matters is that you can also define

the transitions surrounding these data elements. You can get at the meaning and

use behind them, like rolling dice, or playing with a deck of cards. It’s much more

than just metadata describing the data elements at work.

If we want our APIs designs to reflect the meaning and interactions around the

valuable resources we are serving up, we need to work hard to make sure we are

all using common data formats and schema. Schema.org provides us with a good

start, but we also need to invest in more in ALPS registries, directories, and dictio-

naries. These provide machine readable definitions of the common data elements

exchanged between systems and applications, as well as the meaning, relations-

hips, interactions, and transitions that make these data elements valuable in our

digital worlds.

ALPS has been submitted as an Internet Engineering Task Force (IETF) draft, and

provides one possible standard to consider when looking to define the semantics

behind API operations. Visit: http://apis.how/alps-io/ for more information.

ALPS has been submitted as an

Internet Engineering Task Force

(IETF) draft, and provides one

possible standard to consider

when looking to define the se-

mantics behind API operations.

Application-Level Profile Semantics (ALPS)

A data format for defining simple descriptions of application

level semantics, similar in complexity to HTML microformats.

Semantics

Hypermedia

application/alps+xml

application/alps+json

Registry

API Definition 25

Restlet began as an open source Java API framework over a decade ago and has

evolved into an API studio, client, and cloud platform with an API design core. At

the center of the API lifecycle management platform is its API designer which gives

you a visual view of an API and an OpenAPI or RAML view, providing a machine

readable accounting of each API’s contract.

The Restlet Studio allows you to design and document your APIs, starting from

scratch, or import existing API design patterns using OpenAPI for RAML. Using

the Restlet design UI you can shape the paths, parameters, headers and complete

requests and responses for any API. Then, take the definition and actually put it to

work in development, staging, or production environments.

Restlet demonstrates how API design is more than just a momentary phase where

you are developing APIs and is actively defining every stop along the API lifecycle

from design to deprecation. While designing an API in the Restlet API Studio, you

can also work to test and automate using the client, helping ensure a usable and

complete API is designed. The Restlet Client provides a dashboard to verify the

desired API contract in a way that can be shared across teams, with clients, and

across stakeholders.

Once the API design process has matured and evolved and is ready for deploy-

ment, Restlet empowers production deployment by, generating server and client

side code with documentation and a landing page for consumers to access and put

an API to work. The Restlet Cloud provides all the components you need to quickly

deploy, manage, and scale an API, while using the API design studio as the central

place where truth around the API is defined — touching every other aspect of API

operations.

Less of a plug for Restlet, I am hoping it is a demonstration of how API design

is central to every aspect of API operations and can be central to API service

providers. API design isn’t just about the technical design of the surface area of

API requests and responses. It is about designing and defining all aspects of doing

business using APIs.

URL: http://apis.how/restlet/

API design isn’t just about the

technical design of the surfa-

ce area of API requests and

responses. It is about designing

and defining all aspects of

doing business using APIs

The Restlet Platform Story

Reslet has evolved from an open source API framework to an API

lifecycle provider assisting users from design to deprecation.

API Definition26

Apiary Apigee Apimint

Apigee’s API Studio combines their earlier Apigee-127 product, work on the Swagger platform and editor, and their BaaS offering. It allows develo-pers to design, mock, test and share via the online platform. While Apigee Studio is part of the larger Apigee line of products, it is a separate standalo-

Apiary jump-started the modern API design movement by making API de-finitions more than just about API do-cumentation. It allows API designers to define APIs in the machine readable API definition format API blueprint and then mock, share, and publish documentation via a cloud platform.

APIMINT is an API lifecycle ma-nagement tool. With their design first approach, all stakeholders get a platform to collaborate and give feedback on API design and structure. It enables common un-derstanding among development teams.

URL: http://apis.how/apigee/URL: http://apis.how/apiary/ URL: http://apis.how/apimint/

Design Studio Services

Reprezen Mulesoft

Mulesoft provides both a cloud-based and open source version of their API design editor, enabling API designers to craft APIs using the RAML API de-finition format. They can then publish to notebook and manage through other aspects of the API lifecycle with other Mulesoft systems.

RepreZen’s solution focuses spe-cifically on the API design process in large organizations and com-plex ecosystems. API management platforms address various aspects of the downstream lifecycle: packaging, provisioning, metering, proxy, and client portal.

URL: http://apis.how/mulesoft/URL: http://apis.how/reprezen/

The are the companies who are offering commercial studio services in the API design space.

05

Irresistible APIs: Designing web APIs that developers will love

A Web API is a web-style interface developers can use to implement functionali-

ty. Well-designed APIs feel like a natural extension of the application, rather than

just a new interface into the backend database. Designing Web APIs based on

use cases allows an organization to develop irresistible APIs, which developers

can consume easily and supports the business values of that organization.

URL: http://apis.how/irresistible-apis/

Restlet

A full life cycle API provider with API design, deployment, manage-ment and client tooling for driving API operations at any scale. Restlet has matured from an open source API framework to a full API design studio at the heart of a de-ployment and management studio.

URL: http://apis.how/restlet/

API Definition 27

Other Service Providers

APIMATIC Gelato

Providers of an API portal, docu-mentation and presence who also have an interesting UI for helping manage the API design process.

An SDK, continuous integration and documentation platform that has a unique approach to enabling the API design process.

URL: http://apis.how/gelato/URL: http://apis.how/apimatic/

RESTful Web APIs: Services for a Changing World

. With this practical guide, you’ll learn what it takes to design usable REST

APIs that evolve over time. By focusing on solutions that cross a variety of do-

mains, this book shows you how to create powerful and secure applications,

using the tools designed for the world’s most successful distributed compu-

ting system: the World Wide Web.

URL: http://apis.how/restful-web-apis-book/

Stoplight Mashape

Materia

An API marketplace with built in API design tooling to assist in the management of APIs that are pu-blished via the platform, providing another example to look at.

Providing API design, documen-tation, and orchestration services, with a pretty interesting UI for managing API definitions used in the process.

A desktop development environ-ment to design and deploy APIs for use across different applica-tions, providing a desktop pers-pective for the API design process.

URL: http://apis.how/mashape/URL: http://apis.how/stoplight/

URL: http://apis.how/materia/

Some companies that I found to have an interesting approach to API design. They do not necessarily sell API design specific services, but have it baked into their platform.

05

API Definition28

Swagger Editor Mulesoft Apicurio

API Designer is a standalone/embe-ddable editor for RAML (RESTful API Modeling Language) written in JavaS-cript using Angular.JS. By default, the editor uses an in-browser filesystem stored in HTML5 Localstorage.

Design, describe, and document your API on the first open source editor fully dedicated to Swagger-based APIs. The Swagger Editor is great for quickly getting started with the Swagger specification.

The apicurio studio project is a standalone API design studio that can be used to create new or edit existing API designs (using the OpenAPI specification).

URL: http://apis.how/multesoft/URL: http://apis.how/swagger-editor/ URL: http://apis.how/raml/

Tooling - Editors

There are only three API editors that are standalone and open source solutions for platform independent deployment of OpenAPI and RAML.

06

The Importance Of An Open Source Visual API Design Editor

I can’t emphasize enough, the importance of having Apicurio in the API sector,

providing an open source, API definitions driven visual API design editor that

any software provider can embed within their tooling. Apicurio will have a

similar effect on the API sector that the Swagger UI documentation did for do-

cumentation and API definitions, and Apiary had on the world of API design.

URL: http://apis.how/apicurio/.

API Definition 29

Tooling - API Design Guides

Google Microsoft Paypal

The Microsoft REST API Guideli-nes, as a design principle, encou-rages application developers to have resources accessible to them via a RESTful HTTP interface.

A general API design guide from Google, used internally for several years, but recently published on-line. It also including designs for REST as well as gRPC APIs.

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.

URL: http://apis.how/microsoft-dg/URL: http://apis.how/google-dg/ URL: http://apis.how/paypal-dg/

Emulating The Best From Existing API ProvidersI can’t emphasize enough for API designers and architects to emulate existing

design patterns already in use by other API providers. This is what makes the

API Stylebook such a great resources. The project aggregates the best prac-

tices from the API design guides of leading companies on github, allowing

anyone to fork and and implement as part of their design

URL: http://apis.how/api-stylebook/

Cisco White House Cloud Foundry

This document provides guideli-nes and examples for White House Web APIs, encouraging consis-tency, maintainability, and best practices across applications.

Several Cisco business units have teamed up to create this RESTful API design guide. Collectively, this includes DevNet, Collaboration, and the Application Platform Group.

A style guide for the Cloud Con-troller API, acting as a repository for patterns and best practices when designing and developing new API endpoints at Cloud Foun-dry.

URL: http://apis.how/white-house-dg/URL: http://apis.how/cisco-dg/ URL: http://apis.how/cloud-foundry-dg/

Design guides from leading platform providers, allowing anyone to learn from the existing API providers.

06

API Definition30

gRPC is a high-performance open source remote procedure call (RPC) framework

that is often used to deploy APIs across data centers that also supporting load

balancing, tracing, health checks and authentication. While gRPC excels in more

controlled, tightly coupled environments, it is also applicable for delivering resour-

ces to web, mobile, and other Internet connected devices.

When crafting gRPC APIs, you begin by defining the service using Protocol Buffers,

a language and toolset for binary serialization that has support across 10 leading

programming languages. Protocol Buffers can be used to generate client and server

stubs in these programming languages with tight API/client coupling — delivering

a higher level of performance than your average REST API and SDK can.

gRPC API design patterns takes advantage of HTTP/2 advances and uses authenti-

cated bi-directional streaming to deliver APIs that can be scaled to millions of RPC

calls per second. Its an effective approach for larger, more demanding API plat-

forms that have begun to see the performance limitations of a more RESTful API

design approach. gRPC is not ideal for every API implementation, but is definitely

an approach providers should consider when high volumes anticipated, especially

within the data center or other tightly controlled environment.

Google has been using gRPC internally for over a decade now, but has recently

committed to delivering all their public APIs using gRPC in addition to RESTful

APIs, demonstrating that the API design patterns can coexist. This approach makes

it a welcome addition to any microservice style architecture. It has the added be-

nefit of API management features like authentication, tracing, load balancing, and

health checking that are required to deliver high performance.

gRPC is definitely more of an industrial grade API design pattern, shifting APIs into

the next gear when it comes to performance. It also leverages the next generation

of the HTTP protocol, HTTP/2. While not an API design pattern that every API

provider will be working with, they should be aware it exists so that they unders-

tand what it is and the role it plays in the space.

gRPC is a modern open

source high performance

RPC framework that can run

in any environment. It can

efficiently connect services

in and across data centers

gRPC: Open Source RPC framework

An emerging design pattern to consider when crafting high perfor-

mance APIs which possess a tighter contract with clients.

High Performance

Leverages HTTP/2

Load Balancing

Tracing

Health Check

Authentication

API Definition 31

GraphQL is a query language designed by Facebook to build client applications

using a flexible syntax and provide a system for describing the data requirements

and interactions required by each application. GraphQL began as a Facebook

project that soon began powering all their mobile applications. By 2015, became a

formal specification. GraphQL provides a query language for your APIs that allows

users to describe how they would like their API requests be fulfilled. The approach

shifts the API design process to be more about request flexibility requiring API

providers to design all API paths ahead of time. It opts for an augmented query

language over investing in static schema that requires specific API paths.

REST APIs focus on paths to your resources, but GraphQL is all about fields and

data types, with everything accessed through a single API path. GraphQL does a

better job of providing a more comprehensive approach access to data stored in a

database by offloading design to the query layer for interpretation at query render

time. The ability to define what data is returned opens up some interesting approa-

ches to delivering resources, especially when it comes to potentially constrained

network environments.

When it comes to providing access to data used in responsive web and mobile

applications, GraphQL can be successful in allowing application developers to get

exactly what they need for an interface and nothing more. This can increase per-

formance and give UI / UX designers more of a voice in what an API does. Graph-

QL has played a significant role in the evolution of React, Facebook’s open source

framework for deploying user interfaces. React is well-known has achieved some

significant traction in application development circles. This design approach to

delivering data using APIs a natural fit for rapidly delivering web and mobile apps.

GraphQL has seen some significant adoption beyond Facebook, notably at Github

and Pinterest. GraphQL strengths become clear when it is used to deliver com-

plex data stores quickly and efficiently by developers that require a greater level

of control what data they need. While GraphQL is not traditional API design, it is

an important design constraint to consider when planning the future of your API

design practices and toolbox.

Who Is Using It?

GraphQL Voyager - With gra-

phql-voyager you can visua-

lly explore your GraphQL API

as an interactive graph. This

is a great tool when desig-

ning or discussing your data

GraphQL is a query language for APIs

GraphQL is a query language for APIs and a runtime for fulfilling

those queries with your existing data.

API Definition32

This publication is targeting API providers at startups, companies, organizations,

institutions, and government agencies, providing a snapshot of the API sector

specifically dedicated to API definitions. While the primary target of the publi-

cation is API providers, there are also regular updates about best practices, new

tooling, standards, and other aspects of the sector that concern API service provi-

ders, and companies looking to reach API providers in the space.

It is these API service providers that support this publication. These companies

fund the publication of this guide through the sponsorship of feature and short

posts, as well as other designated slots throughout the publication.

These are the companies supporting this edition of API definition:

• 3Scale - http://apis.how/3scale

• Restlet - http://apis.how/restlet

• Tyk - - http://apis.how/tyk

• Runscope - http://apis.how/runscope

If you would like to find out about upcoming publishing opportunities, and suppor-

ting this research, you can email info@apievangelist.com to learn more. This guide is

usually updated monthly with a regular rotation of feature articles, and shorts, as well

as including new specifications, services, tooling, and other relevant elements from

across the API sector--new opportunities emerge on a regular basis.

The primary objective of this publication is to reach and educate API providers

outside the echo chamber, while also including API service providers in this regu-

lar storytelling. The API Evangelist website provides access to the raw research

on API definitions, but this guide is meant to provide an executive summary that

any business or technical user can pick up to get up to speed on the subject.

Email info@apievangelist.com to become a sponsor of API Design today.

SPONSOR

Email info@apievangelist.com

to receive more information

about sponsoring.

Become Sponsor

API Evangelist sponsors make

it so I can dedicate my time to

researching the API space, as

well as provide these guides to

what is going on -- I couldn’t

do it without them.

Striking A Balance

“Thank You!”

About The SponsorsThose Who Make This Publication Possible - Thanks!

API Definition 33

I have been researching the API sector for the last seven years. API Evangelist is the

real time result of this research, providing analysis, links to news, patents, companies,

and the APIs that are making an impact on the space. Since 2012 I have worked to

publish white papers, guides, and other more long form content derived from my

research -- this is the latest attempt to provide access to my API definition research in

a more polished and portable format.

As I monitor the space I keep an eye on what companies, organizations, institutions,

agencies, and individuals are up to, aggregating best practices, services, tooling, spe-

cifications, and the other building blocks that make this API thing work. While there is

a wealth of raw research available publicly on my site, my readers have continued to

request a more refined, polished, distilled down version of my research, resulting in

the delivery of these industry guides.

With this latest release of my API design industry guide, I’m bringing more design

to the table, making the guide look better, but it is also something that is forcing

me to think through the material I provide a little deeper than I did before. Earlier

editions of this guide were quantity over quality, and with this next wave of

guides I’m flipping that over, and emphasizing analysis, storytelling, and smaller,

more refined amounts of content--focusing on helping people make sense of

things, and hopefully not overwhelming them with information.

Along the way, I am also experimenting with new ways of generating revenue and

paying the bills. I have a number of companies asking to sponsor my site, but alas I

only have four logo slots available. These polished versions of my guides give me a

new way to extend sponsorship opportunities to my partners, and companies doing

interesting things in the space. The money helps me dedicate my time to keeping

tabs on what is going on and generating as high-quality content as possible.

Thank you for tuning in, and please let me know how I can make this publication

better -- thanks for your support.

-- Kin Lane

About the PublicationBrought To You By Kin Lane, the API Evangelist

ABOUT

twitter: @kinlane

github: @kinlane

kinlane.com

Kin Lane

twitter: @apievangelist

github: @apievangelist

apievangelist.com

API Evangelist

a

{ “API” : ”Evangel ist ” }

{“API”:”Design”}API Design Patterns, Services, and Tooling From Across The Space

Providing a snapshot of the world of API design. Stepping back and considering other emerging approaches to designing an APIs including hypermedia, GraphQL, and gRPC. Aggregating the best API design from across existing API providers who define the space.