API Descriptions for Humans & Machines
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
Problem
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.
Solution
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:
- Locate a Swagger-based API description — for instance, the Uber API description, via the Swagger Editor provided by swagger.io.
- If a URI for a JSON variant of the API description document isn’t available, simply download a JSON variant to your local disk
- 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
- 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
- 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.
It is worth noting that a majority of the terms used to construct these Linked Data documents come from the Schema.org ontology.
Links
- URIBurner Service
- Virtuoso — URIBurner is just a publicly exposed Virtuoso instance which leverages Virtuoso’s built in Extract, Transform, and Load (ETL) services to construct Data Lakes and publish Linked Open Data
- Faceted Browsing oriented Entity Description Document that describes the Uber API — derived from Swagger JSON document
- Basic Entity Description Document that describes the Uber API — derived from Swagger JSON document
- Swagger.io Editor with the Uber API description loaded
