Describing The Facet Web Service

Here's another demonstration of how Structured Data, in Linked Open Data form, courtesy of RDF Language, enables us achieve what's been otherwise unthinkable i.e., the ability to describe HTTP Services (a/k/a Web Services) with ease while exceeding the wildest fantasies of a now defunct WSDL (Web Services Description Language).

In addition, this also demonstrates the fundamental fact that Web Sites also functional as API (Application Programming Interface) discovery points on HTTP networks such as the Web.

Nanotation based Web Service description that turns this post into a description document for a Facet Action that invocable over HTTP:

{

## Generic Description

@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 the generic search & faceted browsing service on server ods-qa" ;
  schema:mainEntity <#FacetedBrowserSearchAction> ;
  schema:about <#FacetedBrowserSearchAction> .

## Search Action

<#FacetedBrowserSearchAction>
  a schema:Action ;
  oplwebsrv:hasActionWord "search" ;
  schema:description "Search - Faceted Browser Action (host: ods-qa:8896)" ;
  schema:target	<#FacetedBrowserSearchEntryPoint> ;
  wdrs:describedby <#this> .

## Web Service Endpoint 
# Schema.org Terms

<#FacetedBrowserSearchEntryPoint>
  a schema:EntryPoint ;
  schema:name "Search - Faceted Browser Entry Point" ;
  schema:description """
   HTTP Service Endpoint that accepts a variety of parameters that control the Facet search action
   """ ;
  schema:contentType "text/html" , "text/turtle" , "application/json" , "application/rdf+xml" ;
  schema:httpMethod "GET" ;
  schema:url <http://ods-qa.openlinksw.com:8896/fct/> ;
  oplwebsrv:hasParameter 
    <#FacetedBrowserSearchActionParameterQ> ,
    <#FacetedBrowserSearchActionParameterViewType> ,
    <#FacetedBrowserSearchActionParameterSameAs> ,
    <#FacetedBrowserSearchActionParameterOffset> ,
    <#FacetedBrowserSearchActionParameterLimit> ;
  schema:mainEntityOfPage <#this> ;
  wdrs:describedby <#this> .

## Endpoint Parameter Descriptions

<#FacetedBrowserSearchActionParameterQ>
  a oplwebsrv:WebServiceParameter ;
  schema:name "Search text" ;
  schema:description """
   A word or phrase to be used for the Facet free text search. 
   """;
  oplwebsrv:shortDescription "A word or phrase to be used for the Facet free text search. Multiple words should be delimited by '+'"  ;
  oplwebsrv:usageExample "http://ods-qa.openlinksw.com:8896/fct/search?q=linked+data" ;
  oplwebsrv:parameterName "q" ; 
  oplwebsrv:parameterExampleValue "linked+data" ;
  oplwebsrv:isRequired true ;
  wdrs:describedby <#this> . 

<#FacetedBrowserSearchActionParameterViewType>
  a oplwebsrv:WebServiceParameter ;
  schema:name "View orientation" ;
  schema:description """
   Sets the default view orientation of the initial page returned by the Faceted Browsing Service. 
   """;
  oplwebsrv:shortDescription "Sets the default view orientation" ;
  oplwebsrv:parameterName "view:type" ; 
  oplwebsrv:isRequired false ;
  oplwebsrv:parameterValue "entity-types,attribute-names" ;
  oplwebsrv:usageExample "http://ods-qa.openlinksw.com:8896/fct/search?q=linked+data&view:type=entity-types" ;
  oplwebsrv:usageExample "http://ods-qa.openlinksw.com:8896/fct/search?q=linked+data&view:type=attribute-names&same-as=yes&offset=100&limit=100" ;
  wdrs:describedby <#this> . 

<#FacetedBrowserSearchActionParameterSameAs>
  a oplwebsrv:WebServiceParameter ;
  schema:name "sameAs inferencing" ;
  schema:description """
   Determines if owl:sameAs inference and reasoning is applied to 
   the generation of data presented by the entity description page. 
   """;
  oplwebsrv:shortDescription "Enables owl:sameAs inferencing for facet search" ;
  oplwebsrv:usageExample "http://ods-qa.openlinksw.com:8896/fct/search?q=linked+data&view:type=entity-types&same-as=yes" ;
  oplwebsrv:parameterName "same-as" ; 
  oplwebsrv:isRequired false ;
  oplwebsrv:parameterValue "yes" ;
  wdrs:describedby <#this> . 

<#FacetedBrowserSearchActionParameterOffset>
  a oplwebsrv:WebServiceParameter ;
  schema:name "Result offset" ;
  schema:description """
   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:shortDescription "Sets the result set page size for scrolling" ;
  oplwebsrv:usageExample "http://ods-qa.openlinksw.com:8896/fct/search?q=linked+data&view:type=entity-types&same-as=yes&offset=100&limit=100" ;
  oplwebsrv:parameterName "offset" ; 
  oplwebsrv:isRequired false ;
  oplwebsrv:parameterExampleValue "100" ;
  wdrs:describedby <#this> . 

<#FacetedBrowserSearchActionParameterLimit>
  a oplwebsrv:WebServiceParameter ;
  schema:name "Max result entities" ;
  schema:description """
   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:shortDescription "Limits the number of result set entities returned" ;
  oplwebsrv:usageExample "http://ods-qa.openlinksw.com:8896/fct/search?q=linked+data&view:type=entity-types&same-as=yes&offset=100&limit=100" ;
  oplwebsrv:parameterName "limit" ; 
  oplwebsrv:isRequired false ;
  oplwebsrv:parameterExampleValue "100" ;
  wdrs:describedby <#this> . 

}

!End of nanotation