Describing Web Service APIs via a Linked Data Doc — using Schema.org terms

One of the biggest headaches afflicting Web Services (i.e., procedures that you can invoke using the Web’s HTTP protocol) is an inability to describe their actual application programming interfaces (APIs) in a generic machine-readable manner. Fundamentally, this boils down to the fact that APIs aren’t described using a collection of human- and machine-comprehensible sentences that enable development of smart invocation clients.

Here’s an example of a Web Service API description (comprehensible by both a human and a machine) using nanotation:

{
## Generic Description
## Schema.org Terms
@prefix oplwebsrv: <http://www.openlinksw.com/ontology/webservices#> .
@prefix schema: <http://schema.org/> .
@prefix wdrs: <http://www.w3.org/2007/05/powder-s#> .
<#this>
a schema:CreativeWork ;
schema:name "Description of a Generic Search & Faceted Browsing Service, Actions, and Endpoints" ;
schema:mentions <http://linkeddata.uriburner.com/fct/search#this> ;
schema:mainEntity <#FacetedBrowsingService> ;
schema:about <#FacetedBrowsingService> .
<#FacetedBrowsingService>
a schema:WebApplication ;
schema:name "Faceted Browsing Service" ;
schema:alternateName "Data Browsing Service" ;
schema:potentialAction <#FacetedBrowsingAction> .
<#FacetedBrowsingAction>
a schema:Action, schema:SearchAction ;
schema:name "Search — Faceted Browsing Action";
oplwebsrv:hasActionWord "Find" ;
schema:target <http://linkeddata.uriburner.com/fct/search#this> .
<http://linkeddata.uriburner.com/fct/search#this>
a schema:EntryPoint ;
schema:name "Search — Faceted Browsing Service Endpoint" ;
schema:description """HTTP Service Endpoint that accepts a variety of parameters that calibrate Faceted Browsing over
various entity relationship dimensions: entity types, attribute names, attribute values. Parameters include:
q for keywords, view:type for dimension [entity type, attribute names, attribute values].
""" ;
schema:contentType "text/html","application/rdf+xml","text/turtle","application/json" ;
schema:httpMethod "GET" ;
schema:urlTemplate "http://linkeddata.uriburner.com/fct/search(?q,view:type,c-term,s-term,same-as,inference,offset,limit)" ;
schema:url <http://linkeddata.uriburner.com/fct/search>;
schema:mainEntityOfPage <#this> ;
## OpenLink Web Services Ontology Terms
oplwebsrv:isWebServiceOf <#FacetedBrowsingAction> ;
oplwebsrv:endPointURL <http://linkeddata.uriburner.com/fct/search> ;
oplwebsrv:urlTemplate "http://linkeddata.uriburner.com/fct/search(?q,view:type,c-term,s-term,same-as,inference,offset,limit)" ;
oplwebsrv:hasParameter <#FacetedBrowsingServiceParameterQ> ;
oplwebsrv:hasParameter <#FacetedBrowsingServiceParameterViewType> ;
oplwebsrv:hasParameter <#FacetedBrowsingServiceParameterSameAs> ;
oplwebsrv:hasParameter <#FacetedBrowsingServiceParameterOffset> ;
oplwebsrv:hasParameter <#FacetedBrowsingServiceParameterLimit> ;
oplwebsrv:usageExample "http://linkeddata.uriburner.com/fct/search?q=linked+data&view:type=entity-types&same-as=&offset=100&limit=100",
"http://linkeddata.uriburner.com/fct/search?q=linked+data&view:type=entity-types&same-as=yes&offset=100&limit=100" ;
wdrs:describedby <#this> ;
schema:mainEntityOfPage <#this> .
<#FacetedBrowsingServiceParameterQ>
a oplwebsrv:WebServiceParameter ;
schema:name "Faceted Browsing Service Parameter 'q'" ;
schema:description """
This parameter takes a keyword or phrase as its value.
""";
oplwebsrv:usageExample "http://linkeddata.uriburner.com/fct/search?q=linked+data" ;
oplwebsrv:parameterName "q" ;
oplwebsrv:parameterExampleValue "linked+data" ;
wdrs:describedby <#this> ;
schema:mainEntityOfPage <#this> .
<#FacetedBrowsingServiceParameterViewType>
a oplwebsrv:WebServiceParameter ;
schema:name "Faceted Browsing Service Parameter 'view:type'" ;
schema:description """
This parameter takes a literal value that sets the default view orientation
of the initial page returned by the Faceted Browsing Service.
""";
oplwebsrv:parameterName "view:type" ;
oplwebsrv:parameterExampleValue "entity-types" ;
oplwebsrv:usageExample "http://linkeddata.uriburner.com/fct/search?q=linked+data&view:type=entity-types" ;
oplwebsrv:parameterExampleValue "attribute-names" ;
oplwebsrv:usageExample "http://linkeddata.uriburner.com/fct/search?q=linked+data&view:type=attribute-names&same-as=yes&offset=100&limit=100" ;
wdrs:describedby <#this> ;
schema:mainEntityOfPage <#this> .
<#FacetedBrowsingServiceParameterSameAs>
a oplwebsrv:WebServiceParameter ;
schema:name "Faceted Browsing Service Parameter 'same-as'" ;
schema:description """
This parameter determines if owl:sameAs inference and reasoning is applied to
the generation of data presented by the entity description page.
""";
oplwebsrv:usageExample "http://linkeddata.uriburner.com/fct/search?q=linked+data&view:type=entity-types&same-as=yes" ;
oplwebsrv:parameterName "same-as" ;
oplwebsrv:parameterExampleValue "yes" ;
wdrs:describedby <#this> ;
schema:mainEntityOfPage <#this> .
<#FacetedBrowsingServiceParameterOffset>
a oplwebsrv:ServiceParameter ;
schema:name "Faceted Browsing Service Parameter 'offset'" ;
schema:description """
This parameter determines offset (marker) boundary size that enables a user scroll (in either direction) through
data presented in the entity description page of the Faceted Browser Service. Increase using blocks of this value
to page forward or backwards.
""";
oplwebsrv:usageExample "http://linkeddata.uriburner.com/fct/search?q=linked+data&view:type=entity-types&same-as=yes&offset=100&limit=100" ;
oplwebsrv:parameterName "offset" ;
oplwebsrv:parameterExampleValue "100" ;
wdrs:describedby <#this> ;
schema:mainEntityOfPage <#this> .
<#FacetedBrowsingServiceParameterLimit>
a oplwebsrv:WebServiceParameter ;
schema:name "Faceted Browsing Service Parameter 'limit'" ;
schema:description """
This parameter determines maximum size of entity relationships in a query solution that provides
data presented in the entity description page of the Faceted Browser Service. This value remains fixed
when a user is scrolling through a query solution that provides data to a Faceted Browsing Page.
""";
oplwebsrv:usageExample "http://linkeddata.uriburner.com/fct/search?q=linked+data&view:type=entity-types&same-as=yes&offset=100&limit=100" ;
oplwebsrv:parameterName "limit" ;
oplwebsrv:parameterExampleValue "100" ;
wdrs:describedby <#this> ;
schema:mainEntityOfPage <#this> .
}

That’s it.

Some screenshots, courtesy of the nanotation processing and extraction prowess of OSDS (OpenLink Structured Data Sniffer):

Figure 1 — Showing Web Service Entry Point (Endpoint) and Actions Descriptions using Schema.org terms
Figure 2 — Web Service Entry Point (Endpoint) description
Figure 3— Showing View-Type parameter description
Figure 4— Showing OFFET and LIMIT parameter descriptions

Links

[1] OpenLink Structured Data Sniffer

[2] URIBurner Service

[3] OpenLink Virtuoso RDBMS & Data Integration Combo

[4] OpenLink Software