BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage Articles The APIs.json Discovery Format: Potential Engine in the API Economy

The APIs.json Discovery Format: Potential Engine in the API Economy

This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space.

This InfoQ article is part of the series Description, Discovery, and Profiles: The Next Level in Web APIs”. You can subscribe to receive notifications via RSS.

 

In the fast growing world of APIs and microservices, finding just the right API when you are developing a web, or mobile application, or possibly integrating between existing systems, is always a tedious task. Conversely, many API providers struggle with making their valuable API driven resources discoverable and easily accessible to potential consumers. Until 2014 there were just a handful of API directories, where API providers could go to list their APIs, and API consumers could go to find the APIs they needed. While this approach has worked for some time now, it has always been designed exclusively for humans, and not for other applications and systems finding, and making decisions around, the API resources they consume.

APIs.json Launched in May 2014

Then in May 2014, 3Scale, an API management infrastructure provider, partnered with API Evangelist to launch a machine-readable and open API discovery format called APIs.json. The goal of APIs.json is to provide a simple, common format that can be used to index APIs and the supporting elements of API operations. APIs.json works much like the Sitemap XML format. But instead of indexing websites, APIs.json is designed to index APIs and offer that index at a well-known location where API providers can publish an index of their API resources.

APIs.json is designed to give API providers an easy way to update their own index but also allow other search engines, directories, and API service providers access to that local index, making all API resources within the domain discoverable.

A Quick Tour of APIs.json

An APIs.json definition always starts with a basic set of descriptions of who you are, as the header of each file, giving consumers a handful of parameters for describing who is behind an API, including a name, description, image, tags, created date, last modified date, and the url where the APIs.json is published.

Basic set of APIs.json instructions

{
  "name": "API Evangelist",
  "description": "This is an inventory of APIs available as part of the API Evangelist network.",
  "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png",
  "tags": [
    "application programming interface",
    "API",
    "News",
    "Analysis"
  ],
  "created": "2014-04-07",
  "modified": "2014-07-09",
  "url": "http://apievangelist.com/*APIs.json*",
  "SpecificationVersion": "0.14",
  ...
 }

Next is the heart of an APIs.json file - the APIs collection, which gives API providers the ability to describe one or many APIs as part of a collection. Similar to the parameters provided for the header, each API entry is allowed a handful of parameters that describe each API: name, description, image, tags, humanURL (The url any human should visit to learn more about an API), and baseURL (The base url any machine should follow to start using an API).

The heart of an APIs.json file — the APIs collection

  ...
  "apis": [
    {
      "name": "Analysis",
      "description": "Provides access to blog posts and analysis across the API Evangelist network.",
      "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png",
      "humanURL": "http://developer.apievangelist.com",
      "baseURL": "http://api.apievangelist.com/definitions/Analysis",
      "tags": [
        "blog",
        "industry",
        "analysis",
        "new",
        "API",
        "Application Programming Interface"
      ],
      ...
    }
  ]
  ...

After providing a base set of metadata around an API, the properties collection provides publishers with any other reference url an API provider wishes. It is common for APIs.json to begin with four basic properties: X-documentation, X-signup, X-pricing, X-tos. Ultimately you can define any property you wish for an API, but the recommendation is to start with these essential building blocks that any API consumers will be looking for.

Essential building block properties for APIs.json

  ...
  "properties": [
    {
      "type": "X-signup",
      "url": "https://apievangelist.3scale.net/"
    },
    {
      "type": "Swagger",
      "url": "http://api.apievangelist.com/definitions/Analysis"
    },
    {
      "type": "X-blog",
      "url": "http://developer.apievangelist.com/blog/"
    },
    {
      "type": "X-apicommonsmanifest",
      "url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json"
    }
  ],
  ...

The overall description of an APIs.json collection provides details about how the APIs are indexed as part of the collection, but there are also portions of the APIs.json format that allow for the inclusion of contact information, tags, and references to other related APIs.json files. APIs.json is engineered to stay as a basic framework for hanging metadata about API operations, with a very extensible url type format for adding any other external reference that is necessary to fully describe all aspects of API operations.

More than a Discovery Format

When you bring up the topic of API discovery amongst technologists they can be quick to point out some existing solutions for API discovery which often include the adoption of hypermedia patterns early on in the API design lifecycle. As an alternative to these existing API discovery options, APIs.json is focused on indexing the existing, and the rapidly emerging APIs whether they are hypermedia, RESTful, or even SOAP web services. In a perfect world, API designers would follow a common set of design principles but, in reality, we are left with the thousands of ‘snowflake’ API definitions that currently exist across almost every business sector online.

In addition to expanding the API discovery conversation to a variety of service types, APIs.json works to reach beyond just the technology of API discovery. Most published APIs.json files start with providing links to the common technical building blocks of an API, like describing an API's surface area using common API definition formats like API Blueprint or Swagger. But APIs.json files can also provide important business elements like references to documentation, pricing, and API registration or account management. Additionally, APIs.json can be used to record some of the more political aspects of API operations like rate limits, authentication details, terms of service, and privacy. All this make each APIs.json index — with machine readable access — a source for the technical, business, and political building blocks of your API operations.

Self-hosted Discovery

While an APIs.json file will most often live within a single domain (acting as a local API index), the APIs contained in an APIs.json file may also be distributed across any number of public or private locations. That means APIs.json driven collections can provide indexes of APIs while also aggregating them into valuable collections that can be put to work delivering specialized, targeted applications, devices, and system integrations.

(Click on the image to enlarge it)

A fitness API platform like Fitbit has an APIs.json file for its API. So does Link Creation Studio from HP. Each is maintained by its respective API owner. Then anyone — maybe an API broker, or application development agency — can publish their own 3rd party APIs.json file that aggregates both the Fitbit API and the Link Creation Studio API together, establishing a specialized API collection that can be used to develop applications that employ Fitbit data, while providing link and image management resources connecting various applications to the physical world through image watermarks and QR codes.

APIs.json Tooling

Even as an open format, APIs.json offers very little value to either API providers or consumers if there is no tooling available that allows the discovery and exploration of APIs. With this in mind, the first open source APIs.json driven search tool was developed to provide a new take on API discovery; one that possesses its own API, and aggregates all of the machine readable APIs.json files into a single publicly available API search engine, called APIs.io.

In 2015, additional companies have been working on developing 1) internal enterprise API search engines, 2) Google Chrome and Firefox browser tooling, 3) IDE based collections, even 4) spreadsheet consoles and connectivity - all APIs.jsondriven. This is just a glimpse at the tooling currently being developed on APIs.json, looking to assist API providers, consumers, and their systems or applications discover - as well as be discovered - across the increasingly crowded API landscape.

Beyond the open tooling, the potential of APIs.json becomes evident at run-time. Not just within tooling like API search engines, integrated development environments, or the ubiquitous spreadsheet, but as a potential engine within any application providing important details about available API endpoints, authentication details, response codes, the underlying data model employed, licensing options for an API, rate limits, pricing, and other critical aspects of API integration.

With APIs.json, an application can choose its own underlying cloud storage provider based upon price, reliability, licensing, terms of service elements, or even make decisions around which messaging, photo, video or other API resources are put to work, based on this same criteria.

Designed to be Both Simple and Powerful

APIs.json is designed to be a simple, machine readable format that can be published to a commonly known location, crafting an index of one or many APIs — delivering valuable metadata that can be used to make real-time decisions within API search engines, IDEs, spreadsheets, and any other tooling, applications, devices, and system integrations. The APIs.json format begins with discovery, but has the most potential as a potential engine for the API economy.

(Click on the image to enlarge it)

When it comes to API discovery, it is easy to see the experience as a temporary thing. You need to find an API and then you are done; API discovery complete. But, in reality, in the 24/7, always on digital world that we have created for ourselves, this process is going to play out over and over requiring us to be perpetually looking for just the right API to meet our ever evolving needs.

As this API discovery cycle plays itself out, we are going to need more data points than just keyword searches and SOAP vs REST or JSON vs XML style discovery. We will need to be able to make API discovery and adoption decisions based upon the real world data points that deeply affect integration. Data points like pricing, licensing, availability, stability, terms of service, and beyond. We are in desperate need of machine readable descriptions for all these areas of API operations as well as the tooling to find and make sense of it all in real-time.

APIs.json is emerging as the scaffolding on which these valuable, machine readable data points can be hung, opening up API operations to the new generation of API discovery tools. But it also helps make APIs accessible at every other stop along the API lifecycle from discovery and design to management, testing, and monitoring - providing a blueprint for a virtual engine that shows promise in being a driver of the API economy, beyond the technology, and also properly addressing the business and politics of each of the business sectors APIs are touching in 2015.

About the Author

Kin Lane has been working with databases since the late 1980s, with the last five years exclusively focused on the technology, business and politics of Application Programming Interfaces, also known as APIs. Kin works to educate technologists, as well as the “normals” about the importance of data portability, interoperability, security and privacy across the web and mobile application platforms we depend on in our personal and business lives, by advising startups, companies, and the government as a former Presidential Innovation Fellow. You can follow him via his APIEvangelist.com blog and on Twitter @kinlane.

 

This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space.

This InfoQ article is part of the series Description, Discovery, and Profiles: The Next Level in Web APIs”. You can subscribe to receive notifications via RSS.

Rate this Article

Adoption
Style

BT