API definitions are the most important research in my stack in my opinion, focusing on the API definitions, schema, and standards that are being used across the API sector to define every aspect of API operations. These definitions are being used across every stop along this cycle as a sort of central truth, and often are providing a contract that defines operations.
APIs are more about using common web patterns than they are about developing any secret technological sauce. APIs are about enabling applications and systems to speak a common language while providing access to data, content, and algoritihmic resources. The goal of this lesson is to help walk you through at the high level, what API definitons are, and the role they are playing across the API life cycle.
When I start talking about API definitions with technologists, they almost always think about OPenAPI, JSON Schema, and other formats used to define APIs, and their moving parts. When in reality, API definitions can apply to web standards, media types, as well as these common API-focused definitions you hear about today.
API definitions are anything you are using as part of your API operations that has been well-defined, and most likey in use across other APIs, and driving the web as we know it. Know your definitions!
APIs use the web. Websites are meant for humans to interact with in their browsers using HTML, and APIs are meant for applications and disparate systems to share data, content, media, and algorithms across the network. The current wave of APIs are designed to leverage the web, providing a low cost way of delivering API resources in a way that is understandable by many.
When thinking about API definitions always begin and end by thinking about common web concepts already in use to drive the web. There are numerous standards and concepts out there for defining how documents are made available via the web, and APIs should be leveraging these same standards. There are a number of online resources for studying web standards, make sure and spend regular time learning about the existing foundations of the before getting to work defining an API.
Websites return HTML for humans to see in browser, and other applications can also use HTML, but also consumes XML, Atom, JSON, CSV, and a number of other common machine readable formats. These are the commonly used API media types as defined by IANA, providing a base set of content types that all APIs should be serving up.
- text/html - Provide HTML media types for API requests and responses.
- application/xml - Provide XML media types for API requests and responses.
- application/atom+xml - Provide ATOM media types for API requests and responses.
- application/json - Provide JSON media types for API requests and responses.
- application/csv - Provide comma separate value (CSV) media types for API requests and responses.
- text/tab-separated-values - Provide tab separated values (TSV) media types for API requests and responses.
APIs should always work to offer a range of media types which allow consumers to negotiate the best content type for their needs, providing a buffet of machine readable representations for any data, content, or algorithms that are served up. Content negotiation is a fundamental concept of the web that should be present in any modern API.
Beyond the common media types there are a handful of hypermdia media types. These are the leading hypermedia formats being applied during the API design process which can provide a much more rich API integration experience.
- JSON API - 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.
- Collection+JSON - Collection+JSON is a JSON-based read/write hypermedia-type designed to support management and querying of simple collections.
- Siren - 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.
- Hypertext Application Language (HAL) - HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.
- Mason - Mason is a JSON format for introducing hypermedia elements to classic JSON data representations.
Each of these media types bring their own benefits to the table. These definitions bring many of the affordances we take for granted with the web, and many API providers will often look when providing APIs, and delivering clients for use in integration.
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 in this case APIs. Providing one of the most important definitions that can be applied to API operations, essentially teaching your APIs to speak in a language other APIs will immediately recognize and be able to put to use--API integration is easier when we all use the same vocabulary.
Schema.org vocabulary can be used with many different encodings, including RDFa, Microdata and JSON-LD. These vocabularies cover entities, relationships between entities and actions, and can easily be extended through a well-documented extension model. Over 10 million sites use Schema.org to markup their web pages and email messages. Many applications from Google, Microsoft, Pinterest, Yandex and others already use these vocabularies to power rich, extensible experiences.
In the last five years a new breed of API specifications have emerged to help define the growing number of web APIs out there. In the last year it has become clear that OpenAPI has become the leader when it comes to quantifying what an API does. OpenAPI allows for API designers and architects to define the detail of API operations, outlining the nuts and bolts of making an API request, and provides the details of each API response, as well as the data schema in use.
OpenAPI allows one or many APIs to be defined as a group. Providing a machine readable blueprint of the host, and paths, parameters, headers, and every aspect of an APIs surface area. OpenAPI then also allows for the same amount of details about each response, error and status codes, and uses JSON schema to define how data is used as part of each request and reponse. You can define any web API using OpenAPI, defining how data, content, and algorithms are exchange over the web.
Often complimenting API specifications, a number of specifications for defining data have emerged to support API operations. JSON schema is by far the most advanced, and supported specification for defining the details of data used in API requests, and responses. Schema often starts with a database definition, but depending on how it is being access, can significantly be evolved with modern approaches to schema.
Data schemas allow for data objects and arrays to be defined, outlining parameters, their details, and the relationships potentially between elements. Schema provides a shared knowledge around what data is being made available via API operations, and can be taken to the next level when common dictionaries like Schema.org are put to use.
Beyond standards, specifications, and schemas to help define API operations, there is another way to define APIs to make them more usable. When considering a new API, take a look at what is already available in the space, doing the same, or similar things you are looking to do with an API. Then emulate it. Reuse the best patterns already in use by existing API providers is one of the best ways to define a new APIs.
Unfortunately many existing APIs do not have a licensing that applies specifically to the definition of the API, leaving this area of reuse a bit of a gray area. However, many API providers would be fine with resuse of their design patterns and definitions applied if the API compliments their API and doesn't directly compete--if in direct competition, there could be callenges in this portion of defining an API.
Adjacent to the world of APIs, there are many schema and data standards in existence that help guide database implementations, and the sharing of data within specific industries. When beginning any API project, at early stages of defining what it will do, it always helps to study the existing landscape, looking for existing schema already in use.
Many existing data projects would benefit from having an API specification defined on top of the existing schema, providing more guidance on how data can be accessed, and shared. Like API patterns, reinventing the wheel when it comes to data schema just doesn't make sense, and reusing existing schema patterns, even if they don't cover 100% of the use cases makese sense.
When it comes to API definitions there are a growing number of generators available, that empower developers to generate common API definitions in a variety of formats. As API definitions become more prominent, and used across a number of ecosystems, generators will become more common for translating from an existing platform format into something that is portable and can be used anywhere.
Check to see what API specification generators are available for the platforms you are already using. It is pretty likely there is already an OpenAPI, or other format generator. If not, there is an oppotunity for you to develop one, as there are probably other users just like you who would benefit from it's existence.
Adding to the toolbox there are a number of API definition and schema converters emerging that translate and convert from one format into another, putting every leading format in the reach of any API architect. API definition converters come in open source installable versions, as well as an API--as every good API service should.
Do not let yourself get locked into any single API definition format. Even if you do have a preference for one over the others, make sure that API converters, and transformations are in your toolbox, allowing you to speak in almost any API definition format.
Feeding the other side of the beast as generators do, by allowing for common API definitions to be parsed and used within existing platforms, and service providers supporting the API space. Parsers allow common API definitions to be imported into any system, making API definitions something that any platform or service can speak.
Most modern API service provides allow for the importing and parsing of API definition formats. If a platform you depend on does not support parsing of at least one of the common formats, let them know, and point them to the numerous parsers in the space, and the benefits of being fluent in API definitions--the entire platform will benefit from it.
I consider API definitions to be the one stop along the API life cycle that actually touches all the other stops along the API life cycle. API definitions aren't just about design, documentation, and code generation. API definitions are defining testing, monitoring, security, and being used to virtualize and sandbox APIs. API definitions are where you start, work on, and end anything you are doing with APIs.
Ideally, your API life cycle is all about testing your API assumptions, and refining and evolving that definition wherever possible. API definitions are what drives the API lifecycle, keeping resources moving along in a consistent way, while reliably making data, content, media, and algorithms accessible using the web.
As some industries putting to APIs work evolve we are seeing more companies, industry organizations, and government step up to providing common API definitions that any business can employ. In the United States we are seeing healthcare interroperability evolve with the help of Fast Healthcare Interoperability Resources (FHIR). In Europe we are seeing the Payment Services Directive (PSD2) help define the banking API landscape.
OpenAPI has emerged as a leading API specification for use across any business or government sector. We are beginning to see industry specific OpenAPis emerge, helping define common APIs beyond healthcare and banking, into eduction, transportation, manufacturing and other legacy industries. OpenAPIs are also moving beyond the web and providing a common interface for networks, devices, automobiles, signage, manufacturing, and other more physical aspects of our world that are being connected to the Internet.
APIs are the web. They need to be using common standards, specifications, and existing formats already in use. Even as APIs spared to devices, and more physical elements of our world, they should be leveraging the same protocols, and definitions that make the web work. If existing definitions aren't in existence, as new definitions are created they should be put on a road to being openly defined, and eventually graduating to standard status. Common API definitions are essential to all of this continuing to work, and scale to meet the growing number of use cases where APIs are being put to work.