I am Kin Lane, the API Evangelist...

This is my online domain where I work to understand the world of the Application Programming Interfaces, also known as APIs. This new way of sharing data using the web is touching almost every aspect of our increasingly digital lives, providing access to the bits and bytes that make our personal and professional worlds go round.

This is my research specificially into the world of API design, and how API architects and developers are developing and sharing best practices when it comes to crafting their APIs. I've been tracking API since it started becoming a thing back in 2012, and in 2017 it has become a full fledge discpline, with a wealth of services and tooling.

API Evangelist is a network of data driven projects and APIs which I curate and manage as part of this ongoing research, hoping to provide easy access to the moving parts of my work. Everything you see here runs on Github, making everything forkable, and resuable for both humans and machines.

API Evangelist Partners

These are my partners who invest in API Evangelist each month, helping underwrite my research, and making sure I'm able to keep monitoring the API space as I do.

3scale makes it easy to open, secure, distribute, control and monetize APIs, that is built with performance, customer control and excellent time-to-value in mind.

API Design Industry Guide

In the last couple of years, I've seen the concept of API design go from being something the API elite discuss, to something that involves business users, and something that has spawned a whole ecosystem of service and tooling providers.

This API design research covers the concepts people often associate with API design, like REST, and Hypermedia, but also touches on other media types, API definitions, and many of the services, tooling and other solutions that have emerged to serve the space.

I fund my research through consulting, selling my guides, and the generous support of my sponsors. I appreciate your support in helping me continue with my work and hope you find it relevant in your API journey.

Latest From Blog on API Design: Working With My OpenAPI Definitions In An API Editor Helps Stabilize Them

07 Aug 2018

I’m deploying three new APIs right now, using a new experimental serverless approach I’m evolving. One is a location API, another providing API access to companies, and the third involves working with patents. I will be evolving these three simple web APIs to meet the specific needs of some applications I’m building, but then I will also be selling retail and wholesale access to each API once they’ve matured enough. With all three APIs of these APIs, I began with a simple JSON schema from the data source, which I used to generate three rough OpenAPI definitions that will acts the contract seed for my three services.

Once I had three separate OpenAPI contracts for the services I was delivering, I wanted to spend some time hand designing each of the APIs before I imported into AWS API Gateway, generating Lambda functions, loading in Postman, and used to support other stops along the API lifecycle. I still use a localized version of Swagger Editor for my OpenAPI design space, but I’m working to migrate to OpenAPI-GUI as soon as I can. I still very much enjoy the side by side design experience in Swagger Editor, but I want to push forward the GUI side of the conversation, while still retaining quick access to the RAW OpenAPI for editing.

One of the reasons why I still use Swagger Editor is because of the schema validation it does behind the scenes. Which is one of the reasons I need to learn more about Speccy, as it is going to help me decouple validation from my editor, and all me to use it as part of my wider governance strategy, not just at design time. However, for now I am highly dependent on my OpenAPI editor helping me standardize and stabilize my OpenAPI definitions, before I use them along other stops along the API lifecycle. These three APIs I’m developing are going straight to deployment, because they are simple datasets, where I’m the only consumer (for now), but I still need to make sure my API contract is solid before I move to other stops along the API lifecycle.

Right now, loading up an OpenAPI in Swagger Editor is the best sanity check I have. Not just making sure everything validates, but also making sure it is all coherent, and renders into something that will make sense to anyone reviewing the contract. Once I’ve spend some time polishing the rough corners of an OpenAPI, adding summary, descriptions, tags, and other detail, I feel like I can begin using to generate mocks, deploy in a gateway, and begin managing the access to each API, as well as the documentation, testing, monitoring, and other stops using the OpenAPI contract. Making this manual stop in the evolution of my APIs a pretty critical one for helping me stabilize each API’s definition before I move on. Eventually, I’d like to automate the validation and governance of my APIs at scale, but for now I’m happy just getting a handle on it as part of this API design stop along my life cycle.

API Design News

These are the news items I've curated in my monitoring of the API space that have some relevance to the API design conversation and I wanted to include in my research. I'm using all of these links to better understand how the space is designing their APis and the underlying schema used as part of their requests and responses.

If you think there is a link I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.

API Design Organizations

These are the organizations I come across in my research who are doing interesting things in the API space. They could be companies, institutions, government agencies, or any other type of organizational entity. My goal is to aggregate so I can stay in tune with what they are up to and how it impacts the API space.

Collections Of Resources For API Designers. Publicly available API design guidelines are analyzed to list covered topics and their references within each one. All references to a specific topic throughout all analyzed guidelines are easily accessible. Browse each topic and be inspired by references from different guidelines. Design Guidelines cover different topics in different ways, get easy access to all references on each on

Apiary.io is a hosted suite of tools that help companies build web APIs quickly, test and monitor them easily and document them effortlessly. It provides API owners with necessary infrastructure and helps them build relationship with their users. Core of the self-service solution is API Blueprint, an efficient format for describing an API, aspiring to define new gold standard for REST API development. The product uses this Blueprint to streamline adoption of new services and simplify integration to other systems.

Apigee launched their API Studio out of their earlier Apigee-127 product, their work on the Swagger platform and editor, and their BaaS offering. The new studio opens up the ability for developers to design, mock, test and share via their online open source based platform.

APIMATIC is an automatic SDK generator for Hypermedia APIs. Providing SDKs or client libraries not only reduces the time required for your customers to begin consuming your API, but also provides competitor advantage by targeting the variety of programming languages. While the market pressures you to release early and release often, you will often find yourself constrained with respect to time and resources. As a result, maintaining SDKs becomes untenable which ends up becoming a support nightmare.

APIMINT is an API lifecycle management tool. With our design first approach, all stake holders get a platform to collaborate and give feedback on API design and structure. We make sure your all your teams can easily agree and understand your APIs.

Gelato.io is a tool for creating really great API Documentation and Developer Portals. You can describe your API, import and sync with Swagger or API Blueprint, write awesome guides (or get them written for you), have your developers register and get updates when things change, get an automatic API Explorer - everything a good Documentation Site needs and more!

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 with pluggable support for load balancing, tracing, health checking and authentication. It is also applicable in last mile of distributed computing to connect devices, mobile applications and browsers to backend services.

A modern development environment to build advanced mobile and web applications. Materia is an easy-to-use backend to build all kinds of applications (mobile, web, gaming and more). Materia tooling aims to manage the entire development cycle for building enterprise class backends.

MuleSoft provides the most widely used integration platform for connecting SaaS and enterprise applications in the cloud and on-premise. With the rise of cloud and mobile, enterprises face a choice: get overwhelmed by the resulting explosion of end points or seize the opportunity to gain competitive advantage. Founded on the idea that connecting applications should not be hard, MuleSoft lets organizations harness the power of their applications through integration. MuleSoft’s Anypoint™ technology eliminates costly, time-intensive point-to-point integration, enabling business agility.

APISpark is an cloud API platform that lets you create, host, manage and use web APIs. Using the Restlet Framework at its core, APISpark simplifies the web API experience, the time to market, and the overall cost to get started and to scale you APIs. Restlet is a web API platform vendor, pioneer of RESTful web APIs. APISpark serves our customers around the world, providing software to build web APIs, which includes APISpark, the PaaS version of Restlet. APISpark lets you build and deploy your web APIs, which includes the creation, hosting and management--all in one solution.

StopLight provides engineering teams with a new way to document, test, and build web APIs. Our technology easily and automatically maps an API, and then provides tooling and services to reduce development time, and increase reliability and accessibility.

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 defining them. One example for how this works is the Hypertext Markup Language (HTML), which defines the media type text/html and a set of link relation types such as alternate and section. Web Concepts provides a structured, quick, and interlinked overview of these and many more concepts that together establish the Web surface.

If you think there is an organization I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.

API Design Tooling

As I study each API, and API related service, I'm always looking for open source tooling that has been developed around these APIs and API services. This is an aggregate of tooling I've come across and aggregated as part of my API design research.

API Design Guide

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.

Several Cisco business units have teamed up to create this RESTful API design guide. Collectively, this includes DevNet, Collaboration, and the Application Platform Group. The objective of this document is to act as a guide to define the future, it does not represent the current state of all REST APIs at Cisco.

The Microsoft REST API Guidelines, as a design principle, encourages application developers to have resources accessible to them via a RESTful HTTP interface. To provide the smoothest possible experience for developers on platforms following the Microsoft REST API Guidelines, REST APIs SHOULD follow consistent design guidelines to make using them easy and intuitive.

The DTO is working to release draft API design guide describing contemporary best practices in API design and developer empathy. The final document will be mandatory policy that all Commonwealth agencies must follow, and that citizens could be entitled to expect. The agency has published a version control version on Github with a public ticket system for issues and support, and invited our users to help make it better.

This document serves as a style guide for the Cloud Controller API. It is intended to act as a repository for patterns and best practices when designing and developing new API endpoints. This is a living document; It will change over time as we learn more about our users and develop features.

This is a general design guide for networked APIs. It has been used inside Google since 2014 and is the guide we follow when designing Cloud APIs and other Google APIs. It is shared here to inform outside developers and to make it easier for us all to work together. Google Cloud Endpoints developers may find this guide particularly useful when designing gRPC APIs, and we strongly recommend such developers use these design principles.

Purpose of this style guide is to gather a list of rules, best practices, resources and our way of creating REST APIs in Haufe Group. The style guide addresses API Designers, mostly developers and architects, who want to design an API. Intention is to ease the design process by providing helpful rules to create a successful API that your customers will love.

This guide describes a set of HTTP+JSON API design practices, originally extracted from work on the Heroku Platform API. This guide informs additions to that API and also guides new internal APIs at Heroku. We hope it’s also of interest to API designers outside of Heroku. Our goals here are consistency and focusing on business logic while avoiding design bikeshedding. We’re looking for a good, consistent, well-documented way to design APIs, not necessarily the only/ideal way.

To improve the developer experience of API users by converging the OpenStack API to a consistent and pragmatic RESTful design. The working group creates guidelines that all OpenStack projects should follow for new development, and promotes convergence of new APIs and future versions of existing 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, and the wider API industry to follow.

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

API Specification

Barrister is a RPC system that uses an external interface definition (IDL) file to describe the interfaces and data structures that a component implements. It is similar to tools like Protocol Buffers, Thrift, Avro, and SOAP.

The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the servi

RESTful API Description Language (RADL) is an XML vocabulary for describing Hypermedia-driven RESTful APIs. Unlike most HTTP API description languages, RADL focuses on defining a truly hypermedia-driven REST API from the client's point of view. Unlike description languages based on JSON or Markdown, RADL makes it easy to integrate documentation written in HTML or XML. The APIs that RADL describes may use any media type, in XML, JSON, HTML, or any other format.

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.

Data Specification

OData (Open Data Protocol) is an OASIS standard that defines the best practice for building and consuming RESTful APIs. OData helps you focus on your business logic while building RESTful APIs without having to worry about the approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats and query options etc.

Design Editor

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

RAML Store provides a simple storage API plus a persistence plugin which enables you to run the RAML API Designer locally (rather than using a cloud service) and still be able to manage and collaborate on your design. The service is built with node.js, using express and mongodb.

Design Notebook

API Notebook is a web-based, persistent, JavaScript scripting workspace that enables live testing and exploring of APIs, and saving API use cases as markdown gists, so they are versioned, forkable and shareable. It's an example of literate programming. It is provided under the open-source CPAL license.

Hypermedia

HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. Adopting HAL will make your API explorable, and its documentation easily discoverable from within the API itself. In short, it will make your API easier to work with and therefore more attractive to client developers. APIs that adopt HAL can be easily served and consumed using open source libraries available for most major programming languages. It's also simple enough that you can just deal with it as you would any other JSON.

JSON-LD is a lightweight Linked Data format. It is easy for humans to read and write. It is based on the already successful JSON format and provides a way to help JSON data interoperate at Web-scale. JSON-LD is an ideal data format for programming environments, REST Web services, and unstructured databases such as CouchDB and MongoDB.

Mason is a JSON format for introducing hypermedia elements to classic JSON data representations. With Mason, you get hypermedia elements for linking and modifying data, features for communicating to client developers and standardized error handling. Mason is built on JSON, reads JSON, writes JSON and generally fits well into a JSON based eco-system.

Semantic descriptions for hypermedia APIs. RESTdesc allows you to capture the functionality of hypermedia APIs, so automated agents can use them. Despite their powerful capabilities, RESTdesc descriptions are easy to master. The description is not a goal in itself: you want your API to be used. See how RESTdesc opens up your API for discovery, based on its functional characteristics.

Semantics

JSON-LD is a lightweight Linked Data format. It is easy for humans to read and write. It is based on the already successful JSON format and provides a way to help JSON data interoperate at Web-scale. JSON-LD is an ideal data format for programming environments, REST Web services, and unstructured databases such as CouchDB and MongoDB.

gRPC

If there is a tool that you think should be listed here, let me know by submitting a Github issue or Tweeting a link at me. I'm always looking for new types of tools, and get better at organizing them here and making sense.

API Design Building Blocks

As I study the API space, and profile the companies, services, and tooling I come across I'm always looking for the common building blocks in use across API operations. These are the features, and valuable elements of API operations, as well as companies who are servicing the API space.

Best Practices

Use the Internet - The web brings a lot of tools to the table, make sure and learn about existing web technologies, and put them to use across the API design process.

Simplicity - Consider simplicity at ever turn when designing APIs, providing the small possible unit of value you possibly can--simplicity goes a long way.

Consistency - Employ consistent approaches to all aspects of API design, providing a familiar approach across all APIs published.

Easy to Read - While APIs are for computers, they should be easy to read by humans, making documentation more accessible.

Easy to Learn - Keeping APIs simple, and consistent, will contribute to them being easy to learn about for any potential API consumer.

Hard to Misuse - When APIs do one thing, and does it well, you reduce the opportunity for misuse, and people putting them to work in unintended ways.

Audience Focused - APIs should be designed with a specific audience in mind, providing a solution to a problem they are having.

Experience Over Resource - Make APIs reflect how they will be used, and experienced, over where the API came from and the resource it was derived from.

Use Your Own APIs - Always use your own APIs, allowing you to understand the challenges with integrating, as well as the pain of operations and outages.

Notifying API consumers - How to send events or notifications to API consumers

Case - 'Which case (lowercase, camelCase, ...) to use and when'

Global design - General considerations on API design

Naming - How to name things

Design Process

Definitions - Usage of common API definition formats like Swagger, API Blueprint, RAML, and others for describing and defining APIs.

Editor - An IDE for editing API definitions, as well as possible GUI interface for editing all of API details through desktop or web tooling.

Forkable - Allow an API definition to be forked, and built upon using a common API definition format.

Sharing - Allow for API definitions to be shared amongst team members through links, chat, email, and other channels.

Collaboration - Enable the collaboration between users, both technical, as well as business stakeholders.

Annotation - Provide tooling for annotating API definitions that the design it represents, leaving notes and comments at all layers.

Translation - Allowing for the translation of API designs between common API definition formats, allowing users to speak in any format.

Highlighting - Enable highlighting of specific aspects of an API design to differentiate it from other areas, and establishing common patterns.

Error handling

Error format - How to provide information about errors

Errors - How to handle errors

HTTP Methods

PATCH - The PATCH method applies partial modifications to a resource.

OPTIONS - 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.

HEAD - The HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.

GET - The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.

PUT - 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.

POST - The POST method requests that the server accept 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 message for a bulletin board, newsgroup, mailing list, or comment thread; 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.

Forbidden methods alternatives - What to do when only possible HTTP methods are POST and GET

DELETE - The DELETE method deletes the specified resource.

HTTP Status Redirection

303 See Other - The response to the request can be found under another URI using a GET method. When received in response to a POST (or PUT/DELETE), the client should presume that the server has received the data and should issue a redirect with a separate GET message.

302 Found - Common way of performing URL redirection. An HTTP response with this status code will additionally provide a URL in the location header field. The user agent (e.g. a web browser) is invited by a response with this code to make a second, otherwise identical, request to the new URL specified in the location field.

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. In such case, there is no need to retransmit the resource since the client still has a previously-downloaded copy.

301 Moved Permanently - This and all future requests should be directed to the given URI.

HTTP Status Server Error

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

500 Internal Server Error - 'A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.'

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

HTTP Status Success

202 Accepted - The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.

200 OK - 'Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.'

204 No Content - The server successfully processed the request and is not returning any content.

206 Partial Content - The server is delivering only part of the resource (byte serving) due to a range header sent by the client. The range header is used by HTTP clients to enable resuming of interrupted downloads, or split a download into multiple simultaneous streams.

201 Created - 'The request has been fulfilled, resulting in the creation of a new resource.'

HTTP Status User Error

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

411 Length Required - 'The request did not specify the length of its content, which is required by the requested resource.'

408 Request Timeout - The server timed out waiting for the request. According to HTTP specifications: The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time.

406 Not Acceptable - The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.

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

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

415 Unsupported Media Type - 'The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.'

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

403 Forbidden - '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 for the resource.'

423 Locked - The resource that is being accessed is locked.

405 Method Not Allowed - A request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presented via POST, or a PUT request on a read-only resource.

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 intentionally removed and the resource should be purged. Upon receiving a 410 status code, the client should not request the resource in the future. Clients such as search engines should remove the resource from their indices. Most use cases do not require clients and search engines to purge the resource, and a 404 Not Found may be used instead.

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

412 Precondition Failed - The server does not meet one of the preconditions that the requester put on the request.

401 Unauthorized - Similar to 403 Forbidden, but specifically 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 applicable to the requested resource.

Hypermedia

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

Noun As Resource With HyperLinks (NARWHL) - A framework intended to provide a roadmap for those needing to implement an API using current best practices, but is flexible enough to grow into the future.

Siren - A hypermedia specification for representing entities in APIs.

Uniform Basis for Exchanging Representations (UBER) - The UBER message format is a minimal read/write hypermedia type designed to support simple state transfers and ad-hoc hypermedia-based transitions.

XForms - XForms is an XML format used for collecting inputs from web forms, and can be used to describe a user interface and a set of common data manipulation tasks.

XML Inclusions (XInclude) - Inclusion is a format to merge a number of XML information sets into a single composite infoset.

XML Linking Language (XLink) - Allows elements to be inserted into XML documents in order to create and describe links between resources.

xml:id - An ID attribute in XML documents and defines processing of this attribute to identify IDs in the absence of validation, without fetching external resources, and without relying on an internal subset.

Internationalization

Accept-Language - Set the language the API should be speaking using��Accept-Language.

vCard - vCard is a file format standard for electronic business cards. vCards are often attached to e-mail messages, but can be exchanged in other ways, such as on the World Wide Web or instant messaging. They can contain name and address information, telephone numbers, e-mail addresses, URLs, logos, photographs, and audio clips. Use vCard when representing contact data in your API responses.

KML - When working with mapping data, represent it using KML when possible.

ISO 8601 (Date / Time) - ISO 8601 Data elements and interchange formats information interchange representation of dates and times is an international standard covering the exchange of date and time-related data. The purpose of this standard is to provide an unambiguous and well-defined method of representing dates and times, so as to avoid misinterpretation of numeric representations of dates and times, particularly when data are transferred between countries with different conventions for writing numeric dates and times.

ISO 4217 (Currency) - Use ISO 427 data elements and interchange formats for the representation currency codes. ISO 4217 is a standard published by International Organization for Standardization, which delineates currency designators, country codes (alpha and numeric), and references to minor units in three tables: current currency & funds code list, current funds codes, list of codes for historic denominations of currencies & funds.

ISO 3166 (Country) - Use ISO 3166 data elements and interchange formats for the representation country codes. The purpose of ISO 3166 is to define internationally recognized codes of letters and/or numbers that we can use when we refer to countries and subdivisions. However, it does not define the names of countries .

SSL - Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer (SSL), both of which are frequently referred to as 'SSL', are cryptographic protocols designed to provide communications security over a computer network. Always support TLS / SSL by default when it comes to API operations, if at all possible.

Host - Put sufficient thought into what the baseURL will be for making API calls. Increasingly this element can also be dynamic, like other aspects of API design.

Resource - Consider how you craft your resources across all API operations. I do not subscribe to specific philosophies around this, just trying to provide a framework to think about this in.

Action - Allow for standard actions to be taken across resource, but also reflect how APIs will be experienced, providing meaningful action to be taken around any API.

Verbs - Learn about, and put all HTTP verbs to use when designing APIs.There is more than just GET, and even more than just POST, PUT, and DELETE.

Parameters - Standardize how parameters are crafted as part of API operations, using intuitive and consistent approaches.

Headers - Learn about, and use common headers for API requests. Study how the APIs you consumer put headers to work.

Body - Use the body of each request in a consistent way across API operations. The body provides much more room for more structured data and content.

Versioning - Establish, and stick to a common versioning strategy, and use throughout API evolutions. Consider putting all versioning information within headers.

Pagination - Learn about common ways to paginate, and establish a single way to handle across API operations.

Filtering - Consider how filtering will happen across all APIs, and establish a single way to filter API resources.

Time Selection - Consider how time selection and series will be handled, and establish a single way for working with time in API operations.

Sorting - Establish a single approach to how API responses can be sorted, and use across all API resources.

Field Selection - Consider providing a way that API consumers can select which fields are included in API responses.

Granularity - Always be aware of the granularity of your API endpoints, and each resource being exposed, keeping everything as small as possible.

Relationship - Consider how relationships between resources will be handled, and establish a single approach for doing across API operations.

UTF-8 - UTF-8 is a character encoding capable of encoding all possible characters, or code points, in Unicode. The encoding is variable-length and uses 8-bit code units. Make sure you use UTF-8 encoding for your API responses, supporting proper encoding.

These building blocks are constantly being added to and reorganized. If there is something you think should be here feel free to let me know. Remember that this represents my living research, and will evolve, expand and actually seed new research areas as I find the time to pay attention to API definitions.

About This Research

As I keep an eye on the space I curate news, bookmark organizations, watch interesting tools, and try to understand what definitions are being applied by leading API providers. I take everything I find and publish here as part of my research.

I then take this research, and what I've learned and publish stories on the blog, and more long form content like my industry guides, and white papers for customers. This is one way thtat I generate revenue to keep it all going.

If you'd like to see me focus more on API definitions I could use more partners investing in this area, helping me find the time to study more about what is going on. Feel free to contact me directly if you want to talk more about API definitions.