API Descriptions for Humans & Machines

Description of the Uber API using YAML via Swagger.io Editor

These days, Swagger is more or less the de facto standard for API descriptions. It primarily offers API documentation (i.e., description documents), aimed at (English speaking) human readers, automatically produced from APIs specified in two document forms:

  • YAML
  • JSON


That’s all fine, until we attempt to reconcile this documentation approach with the elusive (until now!) goal of creating and exploiting "Smart Agents" whose smartness requires that they understand the APIs.

Likewise, we often need such API documentation to be comprehensible to those who don’t speak or read English.


Smart Agents, and developers who don’t read English, can all still benefit from Swagger API descriptions, courtesy of the transformation services provided by our URIBurner service.

For Smart Agents looking to perform RESTful interactions, driven by self-describing structured data comprised of webby entity relationship graphs (a/k/a Linked Data), this boils down to converting JSON-based API descriptions into RDF-based Descriptions — using any of many document types (e.g., JSON-LD, Turtle, N-Triples, and others).

For non-English readers, this also boils down to Linked Data documents (JSON-LD or Turtle, for example), where entity→attribute→value or subject→predicate→object statements are the fundamental basis for understanding how an API description has been encoded.

Linked Data Rendition of the Uber API Description

The steps for generating a machine- and human-comprehensible API description document from one originally published using Swagger is as follows:

  1. Locate a Swagger-based API description — for instance, the Uber API description, via the Swagger Editor provided by swagger.io.
  2. If a URI for a JSON variant of the API description document isn’t available, simply download a JSON variant to your local disk
  3. Upload your local copy to an HTTP location on the Web so that it can be retrieved by URIBurner — e.g., I’ve uploaded a copy of the Uber API Description to my personal data space
  4. Pass the URI of the API description document — e.g., http://linkeddata.uriburner.com/about/html/http://kingsley.idehen.net/DAV/home/kidehen/Public/Swagger/uber_api_swagger.json — or of a richer document that adds serendipitous discovery of related data to the mix — e.g., http://linkeddata.uriburner.com/describe/?uri=http%3A%2F%2Flinkeddata.uriburner.com%2Fabout%2Fid%2Fentity%2Fhttp%2Fkingsley.idehen.net%2FDAV%2Fhome%2Fkidehen%2FPublic%2FSwagger%2Fuber_api_swagger.json — to our URIBurner Service
  5. Done!

Following the steps above, you’ll have a Linked Data document that enables Humans and Smart Agents alike to explore and comprehend the entity relationships that constitute the Uber API — including all Actions that are invocable thereby.

Here are some screenshots depicting a variety of views of the Linked Data documents about the Uber API.

Basic Entity Description Document about the Uber API
Uber API Description viewed through the OpenLink Data Explorer (ODE) Browser Extension
Faceted Browsing oriented Description Document about the Uber API

It is worth noting that a majority of the terms used to construct these Linked Data documents come from the Schema.org ontology.



Like what you read? Give Kingsley Uyi Idehen a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.