OSDB  OSDB REST API

See also:

API Reference

The OSDB REST API allows an application to retrieve details of the services and service actions known to an OSDB service. Service descriptions can be loaded or unloaded and service actions invoked.

The API is JSON-based. Request and response payloads are always JSON, except where a service action requires a different request MIME type or supports different response MIME types.

Authentication and Access Control

The REST API examples which follow assume an unprotected OSDB REST API which requires no authentication to use it. However, most deployments of OSDB will likely want to control access to the OSDB REST API and OSDB UI. To this end, OSDB includes an access control facility based on ACLs and WebID+TLS+Delegation.

The REST API integrates with the OSDB Access Control layer using two methods:

GET /osdb/api/v1/login
GET /osdb/api/v1/logout

Details of these methods and example client applications demonstrating their use can be found in OSDB REST API - Authentication.

Error Reporting

A failed API request normally returns an HTTP status code of 4XX and a JSON response with the status field set to "error". Field response contains any accompanying error message.

Example

{
    "status": "error",
    "method": "load_service",
    "api": "/osdb/api/v1/services",
    "response": "Failed to load service description. 
                Service description validation failed. 
                A service with this ID is already registered. 
                Use 'unload' or a different service ID."
}

Services

List services

Returns an array of service descriptions for all services registered with the OSDB server.

GET /osdb/api/v1/services

Example

Request
curl -k https://osdb.openlinksw.com/osdb/api/v1/services
Response
{
    "status": "success",
    "method": "list_services",
    "api": "/osdb/api/v1/services",
    "response": [{
        "service_id": "ldp_generic",
        "service_name": "LDP generic",
        "description": "Host-independent Linked Data Platform service",
        "import_source_uri": "http://ods-qa.openlinksw.com:8896/DAV/home/nobody/ldp_svc.host_independent.ttl"
    }, {
    ...
    }, {
        "service_id": "anonymous_facet",
        "service_name": "anonymous_facet",
        "description": null,
        "import_source_uri": "http://ods-qa.openlinksw.com:8896/DAV/home/nobody/fct_svc.ki.170103.cmsb.ttl"
    }]
}

Load service

Loads a service description into the OSDB Service Registry.

POST /osdb/api/v1/services

Payload

The POST body is a JSON object with members:

service_moniker may be omitted when registering a named service. It is only required for an anonymous service (one which does not include a schema:WebApplication in its description). service_moniker must be a single word and be unique across the registered OSDB service IDs.

Example

Request
curl -k -X POST https://osdb.openlinksw.com/osdb/api/v1/services -d '{"service_description_url":"http://ods-qa.openlinksw.com:8896/DAV/home/nobody/csv_extractor_svc.ods-qa.170109.ttl"}' -H 'Content-Type: application/json'
Response
{
    "status": "success",
    "method": "load_service",
    "api": "/osdb/api/v1/services",
    "response": "Loaded service description"
}

Example

Request
curl -k -X POST https://osdb.openlinksw.com/osdb/api/v1/services -d '{"service_description_url":"http://ods-qa.openlinksw.com:8896/DAV/home/nobody/fct_svc.ki.170103.cmsb.ttl", "service_moniker":"anonymous_facet"}' -H 'Content-Type: application/json'
Response
{
    "status": "success",
    "method": "load_service",
    "api": "/osdb/api/v1/services",
    "response": "Loaded service description"
}

Unload service

Removes a service description from the OSDB Service Registry.

DELETE /osdb/api/v1/services/:service_id

Example

Request
curl -k -X DELETE https://osdb.openlinksw.com/osdb/api/v1/services/csv_transformer
Response
{
    "status": "success",
    "method": "unload_service",
    "api": "/osdb/api/v1/services",
    "response": "Unloaded service csv_transformer from the Service Registry"
}

Describe service

Returns a description of a given service.

GET /osdb/api/v1/services/:service_id

Example

Request
curl -k https://osdb.openlinksw.com/osdb/api/v1/services/ldp_generic
Response
 {
    "status": "success",
    "method": "describe_service",
    "api": "/osdb/api/v1/services/:service_id",
    "response": {
        "service_id": "ldp_generic",
        "service_name": "LDP generic",
        "description": "Host-independent Linked Data Platform service",
        "import_source_uri": "http://ods-qa.openlinksw.com:8896/DAV/home/nobody/ldp_svc.host_independent.ttl"
    }
}

Actions

List actions

Returns an array of action descriptions for the actions supported by the given service.

GET /osdb/api/v1/actions/:service_id

Example

Request
curl -k https://osdb.openlinksw.com/osdb/api/v1/actions/uber
Response
{
    "status": "success",
    "method": "list_actions",
    "api": "/osdb/api/v1/actions/:service_id",
    "response": [{
        "action_id": "products",
        "description": "Returns information about the Uber products offered at a given location",
        "entry_point": {
            "http_method": "GET",
            "url_template": "https://sandbox-api.uber.com/v1/products(?latitude,longitude)",
            "url": "https://sandbox-api.uber.com/v1/products",
            "name": "Products — Uber products at a given location",
            "description": "\n    The Products endpoint returns information about the Uber products offered at a given location. \n    The response includes the display name and other details about each product.\n    \n    This endpoint does not reflect real-time availability of the products. Please use the Time \n    Estimates endpoint to determine real-time availability and ETAs of products.\n\n    In some markets, the list of products returned from this endpoint may vary by the time of \n    day due to time restrictions on when that product may be utilized.\n   ",
            "encoding_types": null,
            "content_types": ["application/json", "text/turtle", "application/rdf+xml", "application/ld+json"],
            "parameters": [{
                "parameter_name": "longitude",
                "display_name": "Longitude",
                "description": "Longitude component of location",
                "type": "query",
                "required": 1,
                "permitted_values": null
            }, {
                "parameter_name": "latitude",
                "display_name": "Latitude",
                "description": "Latitude component of location",
                "type": "query",
                "required": 1,
                "permitted_values": null
            }]
        }
    }]
}

Example

Request

curl -k https://osdb.openlinksw.com/osdb/api/v1/actions/facet
Response
{
    "status": "success",
    "method": "list_actions",
    "api": "/osdb/api/v1/actions/:service_id",
    "response": [{
        "action_id": "search",
        "description": "Search — Faceted Browsing Action",
        "entry_point": {
            "http_method": "GET",
            "url_template": "http://ods-qa.openlinksw.com:8896/fct/search(?q,view:type,c-term,s-term,same-as,inference,offset,limit)",
            "url": "http://ods-qa.openlinksw.com:8896/fct/search",
            "name": "Search — Faceted Browsing Search Endpoint",
            "description": "HTTP Service Endpoint that accepts a variety of parameters that calibrate Faceted Browsing over \n   various entity relationship dimensions: entity types, attribute names, attribute values. Parameters include:\n   q for keywords, view:type for dimension [entity type, attribute names, attribute values].\n   ",
            "encoding_types": null,
            "content_types": ["application/json", "application/rdf+xml", "text/html", "text/turtle"],
            "parameters": [{
                "parameter_name": "same-as",
                "display_name": "sameAs inferencing",
                "description": "Enables owl:sameAs inferencing for facet search",
                "type": "query",
                "required": 0,
                "permitted_values": ["yes"]
            }, {
                "parameter_name": "view:type",
                "display_name": "View orientation",
                "description": "Sets the default view orientation",
                "type": "query",
                "required": 0,
                "permitted_values": ["entity-types", "attribute-names"]
            }, {
                "parameter_name": "limit",
                "display_name": "Max result entities",
                "description": "Limits the number of result set entities returned",
                "type": "query",
                "required": 0,
                "permitted_values": null
            }, {
                "parameter_name": "offset",
                "display_name": "Result offset",
                "description": "Sets the result set page size for scrolling",
                "type": "query",
                "required": 0,
                "permitted_values": null
            }, {
                "parameter_name": "q",
                "display_name": "Search text",
                "description": "A word or phrase to be used for the Facet free text search. Multiple words should be delimited by '+'",
                "type": "query",
                "required": 1,
                "permitted_values": null
            }]
        }
    }]
}

Example

Request
curl -k https://osdb.openlinksw.com/osdb/api/v1/actions/ldp_generic
Response
{
    "status": "success",
    "method": "list_actions",
    "api": "/osdb/api/v1/actions/:service_id",
    "response": [{
        "action_id": "read",
        "description": "List a container's details and contents",
        "entry_point": {
            "http_method": "GET",
            "url_template": "(ldpResourceUri)",
            "url": null,
            "name": "LDP Read - Retrieve a resource description",
            "description": "Retrieve a description of an LDP resource or container",
            "encoding_types": null,
            "content_types": ["application/ld+json", "text/turtle"],
            "parameters": [{
                "parameter_name": "ldpResourceUri",
                "display_name": "Resource URL",
                "description": "The URL of an LDPR or LDPC. LDPCs must be terminated by /",
                "type": "uri",
                "required": 1,
                "permitted_values": null
            }]
        }
    }, {
        "action_id": "update",
        "description": "Update an LDP RDF resource",
        "entry_point": {
            "http_method": "PUT",
            "url_template": "(ldpResourceUri)",
            "url": null,
            "name": "LDP-RS Update - Update an RDF resource",
            "description": "Update an RDF resource (LDP-RS) including containers (LDPCs)",
            "encoding_types": ["text/turtle"],
            "content_types": ["text/html"],
            "parameters": [{
                "parameter_name": "ldpResourceUri",
                "display_name": "Resource URL",
                "description": "The URL of an LDPR or LDPC. LDPCs must be terminated by /",
                "type": "uri",
                "required": 1,
                "permitted_values": null
            }]
        }
    }, {
        "action_id": "delete",
        "description": "Delete an LDP resource",
        "entry_point": {
            "http_method": "DELETE",
            "url_template": "(ldpResourceUri)",
            "url": null,
            "name": "LDP Delete - Delete an LDP resource",
            "description": "Deletes an LDP resource or container",
            "encoding_types": null,
            "content_types": "",
            "parameters": [{
                "parameter_name": "ldpResourceUri",
                "display_name": "Resource URL",
                "description": "The URL of an LDPR or LDPC. LDPCs must be terminated by /",
                "type": "uri",
                "required": 1,
                "permitted_values": null
            }]
        }
    }, {
        "action_id": "create",
        "description": "Create an LDP RDF resource",
        "entry_point": {
            "http_method": "POST",
            "url_template": "(ldpResourceUri)",
            "url": null,
            "name": "LDP-RS Create - Create an RDF resource",
            "description": "Create an RDF resource (LDP-RS) including containers (LDPCs)",
            "encoding_types": ["text/turtle"],
            "content_types": ["text/html"],
            "parameters": [{
                "parameter_name": "Slug",
                "display_name": "Suggested name",
                "description": "The suggested name (slug) for the new resource",
                "type": "header",
                "required": 1,
                "permitted_values": null
            }, {
                "parameter_name": "ldpResourceUri",
                "display_name": "Resource URL",
                "description": "The URL of an LDPR or LDPC. LDPCs must be terminated by /",
                "type": "uri",
                "required": 1,
                "permitted_values": null
            }]
        }
    }]
}

Describe action

Returns a single action description for a particular action supported by the given service.

GET /osdb/api/v1/actions/:service_id/:action_id

Example

Request
curl -k https://osdb.openlinksw.com/osdb/api/v1/actions/uber/products
Response
{
    "status": "success",
    "method": "describe_action",
    "api": "/osdb/api/v1/actions/:service_id/:action_id",
    "response": {
        "action_id": "products",
        "description": "Returns information about the Uber products offered at a given location",
        "entry_point": {
            "http_method": "GET",
            "url_template": "https://sandbox-api.uber.com/v1/products(?latitude,longitude)",
            "url": "https://sandbox-api.uber.com/v1/products",
            "name": "Products — Uber products at a given location",
            "description": "\n    The Products endpoint returns information about the Uber products offered at a given location. \n    The response includes the display name and other details about each product.\n    \n    This endpoint does not reflect real-time availability of the products. Please use the Time \n    Estimates endpoint to determine real-time availability and ETAs of products.\n\n    In some markets, the list of products returned from this endpoint may vary by the time of \n    day due to time restrictions on when that product may be utilized.\n   ",
            "encoding_types": null,
            "content_types": ["application/json", "text/turtle", "application/rdf+xml", "application/ld+json"],
            "parameters": [{
                "parameter_name": "longitude",
                "display_name": "Longitude",
                "description": "Longitude component of location",
                "type": "query",
                "required": 1,
                "permitted_values": null
            }, {
                "parameter_name": "latitude",
                "display_name": "Latitude",
                "description": "Latitude component of location",
                "type": "query",
                "required": 1,
                "permitted_values": null
            }]
        }
    }
}

Action help

Returns the help text displayed by the OSDB CLI and UI when help is requested for a particular service action. The help text details the command line options supported by the action.

GET /osdb/api/v1/actions/:service_id/:action_id/help

Example

Request
curl -k https://osdb.openlinksw.com/osdb/api/v1/actions/facet/search/help
Response
{
    "status": "success",
    "method": "action_help",
    "api": "/osdb/api/v1/actions/:service_id/:action_id/help",
    "response": {
        "service_id": "facet",
        "action_id": "search",
        "help_text": "\nAction options:\n\n-s, --same_as [same_as]\n\tEnables owl:sameAs inferencing for facet search\n\tRequired: no\n\tPermitted values: yes\n-v, --view_type [view_type]\n\tSets the default view orientation\n\tRequired: no\n\tPermitted values: entity-types, attribute-names\n-l, --limit [limit]\n\tLimits the number of result set entities returned\n\tRequired: no\n-o, --offset [offset]\n\tSets the result set page size for scrolling\n\tRequired: no\n-q, --q <q>\n\tA word or phrase to be used for the Facet free text search. Multiple words should be delimited by '+'\n\tRequired: yes\n-u, --url_only [url_only]\n\tReturn only the action URL, not the action results\n\tRequired: no\n-r, --response_format [response_format]\n\tSets the response media type through an Accept header.\n\tRequired: no\n\tPermitted values: application/json, application/rdf+xml, text/html, text/turtle\n-t, --quality_values [quality_values]\n\tQuality value string. e.g. application/json;q=1.0,text/turtle;q=0.8,*/*;q=0.5. \n\t--response_format takes precedence.\n\tRequired: no\n"
    }
}

When output to the console, the above help text appears as:

Action options:

-s, --same_as [same_as]
    Enables owl:sameAs inferencing for facet search
    Required: no
    Permitted values: yes
-v, --view_type [view_type]
    Sets the default view orientation
    Required: no
    Permitted values: entity-types, attribute-names
-l, --limit [limit]
    Limits the number of result set entities returned
    Required: no
-o, --offset [offset]
    Sets the result set page size for scrolling
    Required: no
-q, --q <q>
    A word or phrase to be used for the Facet free text search. Multiple words should be delimited by '+'
    Required: yes
-u, --url_only [url_only]
    Return only the action URL, not the action results
    Required: no
-r, --response_format [response_format]
    Sets the response media type through an Accept header.
    Required: no
    Permitted values: application/json, application/rdf+xml, text/html, text/turtle
-t, --quality_values [quality_values]
    Quality value string. e.g. application/json;q=1.0,text/turtle;q=0.8,*/*;q=0.5. 
    --response_format takes precedence.
    Required: no

Execute action

Executes a registered service action and returns any output from the action.

POST /osdb/api/v1/actions/:service_id/:action_id/exec

Example

Request
curl -ik -X POST -d '{ "latitude":"37.7759792", "longitude":"-122.41823" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/uber/products/exec
Response
{
    "products": [{
        "capacity": 2,
        "product_id": "26546650-e557-4a7b-86e7-6a3942445247",
        "price_details": null,
        "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-uberx.png",
        "cash_enabled": false,
        "shared": true,
        "short_description": "POOL",
        "display_name": "POOL",
        "product_group": "rideshare",
        "description": "Share the ride, split the cost."
    }, {
         ...
    }, {
        "capacity": 4,
        "product_id": "3ab64887-4842-4c8e-9780-ccecd3a0391d",
        "price_details": null,
        "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-taxi.png",
        "cash_enabled": false,
        "shared": false,
        "short_description": "TAXI",
        "display_name": "TAXI",
        "product_group": "taxi",
        "description": "TAXI WITHOUT THE HASSLE"
    }]
}

Response Payload

The response returned by 'execute action' differs from that of the other OSDB REST API methods in that the latter alway return a JSON object of the form:

 {
    "status": "success" | "error",
    "method": <method_name>,
    "api": <method URI template>,
    "response": ...
 }

In contrast, on successful execution of an action, 'execute action' returns the output from the service action directly, not contained in a JSON wrapper. The data returned in the POST response body may be:

  1. the raw action output
  2. a URL encapsulating the action request which executes the action when dereferenced (only for actions using GET)
  3. RDF generated from the action output
  4. a URL to an RDF viewer's display of the generated RDF

Options 2-4 are controlled by OSDB-specific parameters. These are request parameters recognized by the OSDB server itself, not the action being invoked. The OSDB parameters are described in section 'OSDB Parameters' below.

Error Response

If 'execute_action' fails, it returns a JSON object similar to the other REST API methods. e.g.

Bad Request
curl -ik -X POST -d '{ "latitude":"37.7759792", "longitude":"-122.41823" }' -H 'Content-Type: text/plain' https://osdb.openlinksw.com/osdb/api/v1/actions/uber/products/exec
Response
{
    "status": "error",
    "method": "execute_action",
    "api": "/osdb/api/v1/actions/:service_id/:action_id/exec",
    "response": "Unsupported content type. It must be application/json."
}

Action Parameters

Any parameters required by the action are supplied as a JSON object (referred to as the parameter object in the remainder of this section) in the POST body. The POST request should always include the header Content-Type: application/json.

Below is a cutdown version of the response from list_actions (see "List actions" above) showing the "Uber" service's "products" action description.

GET /osdb/api/v1/actions/uber output:

{
   "status": "success",
    "method": "list_actions",
    "api": "/osdb/api/v1/actions/:service_id",
    "response": [{
        "action_id": "products",
        "entry_point": {
            "http_method": "GET",
            "url_template": "https://sandbox-api.uber.com/v1/products(?latitude,longitude)",
            "content_types": ["application/json", "text/turtle", "application/rdf+xml", "application/ld+json"],
            "parameters": [{
                "parameter_name": "longitude",
                "type": "query",
                "required": 1
            }, {
                "parameter_name": "latitude",
                "type": "query",
                "required": 1
            }]
        }
    }]
}
Parameter Types

The example above includes two 'query' parameters, for supplying name-values pairs in a query string. OSDB recognizes other parameter types for injecting parameter values at different locations in an HTTP request invoking an action.

The parameter types supported are: "query", "header", "uri", "path" and "body".

A parameter's type is set in the RDF service description using the property oplwebsrv:parameterType. If the description of an oplwebsrv:WebServiceParameter omits the oplwebsrv:parameterType property, the parameter is assumed to be a query parameter.

The value of the type property in the action description is not relevant to the parameter object, in so far as OSDB ensures that parameters are injected in the correct location in the HTTP request. Irrespective of the parameter type, the parameter object should include a name-value pair for each parameter being supplied, where name matches the parameter_name value in the JSON action description (or the oplwebsrv:parameterName value in the original RDF service description loaded into the OSDB Registry).

Query Parameters

The parameter object should include a name-value pair for each 'required' action parameter, and optionally a name-value pair for any optional parameter (indicated by "required": 0 in the parameter description). The parameter name in the parameter object should match the parameter_name value from the action description.

Header Parameters

Parameters of type "header" should also be supplied as name-value pairs in the parameter object. For instance, the csv_transformer service includes a "header" parameter which sets the value of the Content-Location header:

"parameters": [{
    "parameter_name": "Content-Location",
   "type": "header",
   "required": 1,
    }, ...

The corresponding member in the parameter object might be:

"Content-Location": "http://ods-qa.openlinksw.com:8896/DAV/home/nobody/pubs.csv"
URI Parameters

A 'uri' parameter supplies a URI for an action. In the following example, taken from a host-independent RDF description of a Virtuoso LDP service, parameter 'ldpResourceUri' identifies the target resource for an LDP DELETE request.

<#LdpDelete_EntryPoint>
  a schema:EntryPoint ;
  schema:name "LDP Delete - Delete an LDP resource" ;
  schema:description """Deletes an LDP resource or container""" ;
  schema:httpMethod "DELETE" ;
  schema:urlTemplate "(ldpResourceUri)" ; 
  oplwebsrv:isEntryPointOf <#LdpDelete> ;
  oplwebsrv:hasParameter 
    <#LdpParamResourceUri> ;
  oplwebsrv:usageExample 
    """curl -iX DELETE -u dav:dav http://example.ldpservice.local/DAV/ldp/bob_foaf""" ; 
  wdrs:describedby <#this> . 

<#LdpParamResourceUri>
  a oplwebsrv:WebServiceParameter ;
  oplwebsrv:parameterName "ldpResourceUri" ; 
  schema:name "Resource URL" ;
  schema:description "The URL of an LDPR or LDPC. LDPCs must be terminated by /" ;
  oplwebsrv:parameterType "uri" ;
  oplwebsrv:isRequired true ;
  wdrs:describedby <#this> . 

A corresponding entry in the parameter object might take the form:

{
    "ldpResourceUri": "http://example.ldpservice.local/DAV/ldp/my_ldpc/" ,
    ...
}
Path Parameters

A 'path' parameter provides a path segment for insertion into a URI template. In this example, the LDP service description ties the LDP service to a specific host. When identifying an LDP resource to be deleted, a client need only supply the resource path, via a 'path' parameter, as the target host is already known.

 <#LdpFixedHostDelete_EntryPoint>
  a schema:EntryPoint ;
  schema:name "LDP Delete - Delete an LDP resource" ;
  schema:description """Deletes an LDP resource or container""" ;
  schema:httpMethod "DELETE" ;
  schema:urlTemplate "http://example.ldpservice-fixedhost.local(/ldprPath)" ; 
  oplwebsrv:isEntryPointOf <#LdpFixedHostDelete> ;
  oplwebsrv:hasParameter 
    <#LdpFixedHostParamResourcePath> ;
  oplwebsrv:usageExample 
    """curl -iX DELETE -u dav:dav http://example.ldpservice-fixedhost.local/DAV/ldp/bob_foaf""" ; 
  wdrs:describedby <#this> . 

<#LdpFixedHostParamResourcePath>
  a oplwebsrv:WebServiceParameter ;
  oplwebsrv:parameterName "ldprPath" ; 
  schema:name "Resource Path" ;
  schema:description "The absolute path (without protocol) to an LDPR or LDPC. LDPCs must be terminated by /" ;
  oplwebsrv:parameterType "path" ;
  oplwebsrv:isRequired true ;
  wdrs:describedby <#this> .

The corresponding entry in the parameter object uses attribute name "ldprPath":

 { 
    "ldprPath": "/DAV/ldp/my_ldpc/" ,
    ...
 }
Body Parameters

Body parameters are described in section "Action Request Body Handling". Please refer to that section for more details.

Constrained Parameters

Some service actions restrict the permitted values of a parameter to a limited set. This is reflected by a parameter's permitted_values property in the action description. It is the responsibility of the client to ensure that the value it supplies for a constrained parameter is one of the permitted values.

The description for the 'Facet' service's 'search' action, returned by

curl -k https://osdb.openlinksw.com/osdb/api/v1/actions/facet/search

includes several constrained parameters.

{
    "status": "success",
    "method": "describe_action",
    "api": "/osdb/api/v1/actions/:service_id/:action_id",
    "response": {
        "action_id": "search",
        "description": "Search — Faceted Browsing Action",
        "entry_point": {
            "http_method": "GET",
            "url_template": "http://ods-qa.openlinksw.com:8896/fct/search(?q,view:type,c-term,s-term,same-as,inference,offset,limit)",
            "url": "http://ods-qa.openlinksw.com:8896/fct/search",
            "name": "Search — Faceted Browsing Search Endpoint",
            "description": "HTTP Service Endpoint that accepts a variety of parameters that calibrate Faceted Browsing over \n   various entity relationship dimensions: entity types, attribute names, attribute values. Parameters include:\n   q for keywords, view:type for dimension [entity type, attribute names, attribute values].\n   ",
            "encoding_types": null,
            "content_types": ["application/json", "application/rdf+xml", "text/html", "text/turtle"],
            "parameters": [{
                "parameter_name": "same-as",
                "display_name": "sameAs inferencing",
                "description": "Enables owl:sameAs inferencing for facet search",
                "type": "query",
                "required": 0,
                "permitted_values": ["yes"]
            }, {
                "parameter_name": "view:type",
                "display_name": "View orientation",
                "description": "Sets the default view orientation",
                "type": "query",
                "required": 0,
                "permitted_values": ["entity-types", "attribute-names"]
            }, {
                ...         
            }, {
                "parameter_name": "q",
                "display_name": "Search text",
                "description": "A word or phrase to be used for the Facet free text search. Multiple words should be delimited by '+'",
                "type": "query",
                "required": 1,
                "permitted_values": null
            }]
        }
    }
}

OSDB Parameters

Action requests can include OSDB-specific parameters to control the action output. All OSDB parameters have a name prefix of osdb:. The OSDB-specific parameters are:

Example Request

Using "osdb:response_format": "application/rdf+xml"

curl -ik -X POST -d '{ "q":"skiing", "osdb:response_format": "application/rdf+xml" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/facet/search/exec
    
<rdf:RDF xmlns:res="http://www.w3.org/2005/sparql-results#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:nodeID="rset">
<rdf:type rdf:resource="http://www.w3.org/2005/sparql-results#ResultSet" />
    <res:resultVariable>res</res:resultVariable>
    <res:solution rdf:nodeID="r0">
      <res:binding rdf:nodeID="r0c0">
          <res:variable>res</res:variable>
          <res:value rdf:parseType="Literal">
          <row>
              <column datatype="trank">12</column>
              <column datatype="erank">5.881291583872891e-14</column>
              <column datatype="url" shortform="http://ods-qa.openli...ki_resorts#Mayhofen">http://ods-qa.openlinksw.com:8896/ski_resorts#Mayhofen</column>
              ...
Example Request

Using "osdb:output_type": "url_only"

curl -ik -X POST -d '{ "q":"skiing", "osdb:output_type": "url_only" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/facet/search/exec

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
...

http://ods-qa.openlinksw.com:8896/fct/search?q=skiing
RDF Generation

The option to generate RDF from the action using "osdb:output_type" : "generate_rdf" is dependent on there being an RDF generator configured for the service, or that the service can output RDF directly.

This extract from an Uber service description shows that conversion of the Uber output to RDF (aka Linked Data) is performed by linking an 'Uber' Sponger cartridge to the service through the oplwebsrv:rdfGenerator property.

<#UberProductsEntryPoint>
  a schema:EntryPoint ;
  schema:name "Products — Uber products at a given location" ;
  schema:contentType "application/json" ;
  schema:httpMethod "GET" ;
  schema:urlTemplate "https://sandbox-api.uber.com/v1/products(?latitude,longitude)" ; 
  oplwebsrv:isEntryPointOf <#UberProductsAction> ;
  oplwebsrv:hasParameter 
    <#UberProductsParamLatitude> ,
    <#UberProductsParamLongitude> ;
  oplwebsrv:usageExample 
    """curl -H 'Authorization: Token sT1eIxxxx' 'https://sandbox-api.uber.com/v1/products?latitude=37.7759792&longitude=-122.41823'""" ; 
  oplwebsrv:securityScheme <#UberProductsSecurityScheme> ;
  oplwebsrv:rdfGenerator <http://ods-qa.openlinksw.com:8896/ext/uber_content> ;
  oplwebsrv:rdfViewer <#UberProductsRdfViewer> ;
  wdrs:describedby <#this> . 

The next example illustrates the use of oplwebsrv:rdfGenerator "self" to indicate that a service (in this case a Virtuoso Sponger cartridge/transformer) is capable of outputting RDF directly.

<#CsvLDGenTransformEntryPoint>
  a schema:EntryPoint ;
  schema:name "Transform — CSV to RDF Transformer Endpoint" ;
  schema:description """HTTP service endpoint that accepts a variety of parameters which control 
   the conversion of CSV data to Linked Data by the OpenLink CSV transformer.
   """ ;
  schema:encodingType 
    "text/csv", 
    "text/tab-separated-values" ;
  schema:contentType
    "application/rdf+xml" ,
    "application/ld+json" ,
    "text/turtle" ;
  schema:httpMethod "POST" ;
  schema:url <http://ods-qa.openlinksw.com:8896/ldgeneration> ;
  schema:urlTemplate "http://ods-qa.openlinksw.com:8896/ldgeneration(?extractor)" ; 
  oplwebsrv:isEntryPointOf <#CsvLDGenTransformAction> ;
  oplwebsrv:hasParameter 
    <#CsvTransformParamExtractor> ,
    <#CsvTransformParamBaseUri> ;
  oplwebsrv:usageExample 
    """curl -i -H \"Content-Type: text/csv\" -H \"Accept: application/rdf+xml\" -H \"Content-Location: http://fp3.com/trentino/pub\" --data-binary @osterie.csv -X POST \"http://ods-qa.openlinksw.com:8896/ldgeneration?extractor=csv\" """ ;
  oplwebsrv:rdfGenerator "self" ;
  oplwebsrv:rdfViewer <#CsvTransformerRdfViewer> ;
  wdrs:describedby <#this> . 
Example Request

Using "osdb:output_type":"generate_rdf", "osdb:response_format":"application/rdf+xml"

curl -ikL -X POST -d '{ "latitude":"37.7759792", "longitude":"-122.41823", "osdb:output_type":"generate_rdf", "osdb:response_format":"application/rdf+xml" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/uber/products/exec

HTTP/1.1 200 OK
Content-Type: application/rdf+xml; charset=utf-8
...

<?xml version="1.0" encoding="utf-8" ?>
<rdf:RDF
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
    xmlns:pwdr="http://www.w3.org/2007/05/powder-s#"
    xmlns:schema="http://schema.org/"
    xmlns:opl="http://www.openlinksw.com/schema/attribution#"
    xmlns:sioc="http://rdfs.org/sioc/ns#"
    xmlns:ns6="http://www.openlinksw.com/ontology/uber#" >
  <rdf:Description rdf:about="http://schema.org/">
    <rdf:type rdf:resource="http://www.openlinksw.com/schema/attribution#DataSource" />
    <opl:hasNamespacePrefix>schema</opl:hasNamespacePrefix>
  </rdf:Description>
  <rdf:Description rdf:about="https://sandbox-api.uber.com/v1/products?latitude=37.7759792&amp;longitude=-122.41823">
    <rdf:type rdf:resource="http://schema.org/CreativeWork" />
    <schema:about rdf:resource="http://ods-qa.openlinksw.com:8896/about/id/entity/https/sandbox-api.uber.com/v1/products?latitude=37.7759792&amp;longitude=-122.41823" />
    <schema:mainEntity rdf:resource="http://ods-qa.openlinksw.com:8896/about/id/entity/https/sandbox-api.uber.com/v1/products?latitude=37.7759792&amp;longitude=-122.41823" />
    <opl:providedBy rdf:resource="https://www.uber.com/#this" />
  </rdf:Description>
  <rdf:Description rdf:about="http://ods-qa.openlinksw.com:8896/about/id/entity/https/sandbox-api.uber.com/v1/products?latitude=37.7759792&amp;longitude=-122.41823">
    <sioc:container_of rdf:resource="http://ods-qa.openlinksw.com:8896/about/id/entity/https/sandbox-api.uber.com/v1/products?latitude=37.7759792&amp;longitude=-122.41823#Product_2832a1f5-cfc0-48bb-ab76-7ea7a62060e7" />
    <sioc:container_of rdf:resource="http://ods-qa.openlinksw.com:8896/about/id/entity/https/sandbox-api.uber.com/v1/products?latitude=37.7759792&amp;longitude=-122.41823#Product_8920cb5e-51a4-4fa4-acdf-dd86c5e18ae0" />
    ...
RDF Viewing

If a service is configured to generate RDF through a Virtuoso Sponger cartridge, the configuration can also include the option to view the RDF in an RDF viewer. Virtuoso supports several RDF viewers. The 'uber' and 'csv_transformer' services above opt to use the Virtuoso /describe service to display the generated RDF, by virtue of the oplwebsrv:RdfViewer declarations:

<#UberProductsRdfViewer>
  a oplwebsrv:RdfViewer ;
  schema:urlTemplate "http://ods-qa.openlinksw.com:8896/describe/(?url)" ; 
  wdrs:describedby <#this> . 

and

  <#CsvTransformerRdfViewer>
  a oplwebsrv:RdfViewer ;
  schema:urlTemplate "http://ods-qa.openlinksw.com:8896/describe/(?url)" ; 
  wdrs:describedby <#this> . 

Including OSDB parameter "osdb:output_type" : "display_rdf" in the 'execute action' parameter object results in the method returning a URL to the /describe service which automatically displays the 'primary' entity in the generated RDF.

"display_rdf" implies use of "generate_rdf" and, in addition, that the generated RDF is saved to the quad store of the Virtuoso instance hosting the Sponger cartridge. The RDF viewer service must be hosted on the same instance. (This need not be same as the OSDB Service Registry host.)

Example Request

Using "osdb:output_type":"display_rdf"

curl -ikL -X POST -d '{ "latitude":"37.7759792", "longitude":"-122.41823", "osdb:output_type":"display_rdf" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/uber/products/exec

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
...

http://ods-qa.openlinksw.com:8896/describe/?url=http%3A%2F%2Fods-qa.openlinksw.com%3A8896%2Fabout%2Fid%2Fentity%2Fhttps%2Fsandbox-api.uber.com%2Fv1%2Fproducts%3Flatitude%3D37.7759792%26longitude%3D-122.41823

Action Request Body Handling

The nature of any data supplied in the body of an HTTP request invoking an action is obviously determined by the target service.

OSDB views this data in one of two ways:

An example of an opaque block might be CSV data supplied to a Virtuoso Sponger cartridge for transformation to Linked Data. OSDB supplies the data to the csv_transformer service as, in its view, a single block of unstructured data with no knowledge of the internal structure.

An example of a transparent structured block might be a POST body containing JSON data.

Body Encoding

If an action requires body content, this is indicated by the presence of schema:encodingType in the EntryPoint description. e.g.

<#CsvLDGenTransformEntryPoint>
  a schema:EntryPoint ;
  schema:name "Transform — CSV to RDF Transformer Endpoint" ;
  schema:encodingType 
    "text/csv", 
    "text/tab-separated-values" ;
  schema:httpMethod "POST" ;
  schema:urlTemplate "http://ods-qa.openlinksw.com:8896/ldgeneration(?extractor)" ; 
  oplwebsrv:isEntryPointOf <#CsvLDGenTransformAction> ;
  oplwebsrv:hasParameter 
    <#CsvTransformParamExtractor> ,
    <#CsvTransformParamBaseUri> ;
  oplwebsrv:usageExample 
    """curl -i -H \"Content-Type: text/csv\" -H \"Accept: application/rdf+xml\" -H \"Content-Location: http://fp3.com/trentino/pub\" --data-binary @osterie.csv -X POST \"http://ods-qa.openlinksw.com:8896/ldgeneration?extractor=csv\" """ ;
  wdrs:describedby <#this> . 

<#CsvTransformParamExtractor>
  a oplwebsrv:WebServiceParameter ;
  oplwebsrv:parameterName "extractor" ; 
  schema:name "Transformation Service" ;
  oplwebsrv:shortDescription "ID of the transformer to be used" ;
  oplwebsrv:isRequired true ;
  oplwebsrv:parameterValue "csv" ;
  wdrs:describedby <#this> . 

<#CsvTransformParamBaseUri>
  a oplwebsrv:WebServiceParameter ;
  oplwebsrv:parameterName "Content-Location" ; 
  oplwebsrv:parameterType "header" ;
  schema:name "Base URI" ;
  oplwebsrv:shortDescription """
    Base URI to be used as the stem for all generated entity URIs.
    Typically it is set to match the URI of the document providing the CSV data.
    """ ;
  oplwebsrv:isRequired true ;
  wdrs:describedby <#this> . 
Supplying Body Content to OSDB

OSDB's view of the body content is determined by how the body is described in the service description, specifically by the presence or absence of parameters of type oplwebsrv:parameterType "body".

If the service description includes schema:encodingType but not any oplwebsrv:parameterType "body" parameters, OSDB handles the body content as an opaque block.

When the service description includes body parameters, these parameters are supplied as name:value pairs in the JSON parameter object sent to OSDB's 'execute action' method (POST /osdb/api/v1/actions/:service_id/:action_id/exec).

Opaque Content

The OSDB REST API obtains opaque body content via a property body_data_src_url. (The OSDB CLI includes an equivalent option -d, --data_url <data_url> for specifying the URL of the action's input data.) This must be added by an OSDB client to the JSON parameter object sent to the 'execute action' method, alongside any other service-specific or OSBD-specific non-body parameters in the parameter object.

For instance, for the CSV transformer service description extract above, the parameter object sent to 'execute action' might take the form

#execute_action: req.body { 
  'Content-Location': 'http://xyz',
  body_data_src_url: 'http://ods-qa.openlinksw.com:8896/DAV/home/nobody/pubs.csv',
  extractor: 'csv',
  'osdb:output_type': 'generate_rdf',
  'osdb:response_format': 'application/ld+json' 
}

where file pubs.csv contains the CSV data to be transformed. OSDB dereferences the file's URL and passes its contents "as is" to the target service as the body of the HTTP request generated by OSDB to invoke the service action. The request includes a Content-Type header set to match schema:encodingType in the EntryPoint description.

Body Parameters (Not yet implemented)

If the service description defines one or more oplwebsrv:WebServiceParameters of type oplwebsrv:parameterType "body", an OSDB client should add them to the parameter object alongside any other service-specific or OSBD-specific parameters.

When generating the HTTP request for the target action, OSDB will generate an HTTP request body which contains the body parameters in a data format dictated by the schema:encodingType in the EntryPoint description. e.g. if the target action expects a POST body encoding of application/json, OSDB will package the body parameters as JSON. Other non-body service-specific parameters will be added to the request in the appropriate location, i.e. in a request header, in a query string or substituted into the request URL template etc. No OSDB-specific parameters are included in the action request.

TO DO: Add body parameter handling to OSDB

TO DO: In the OSDB UI, add form input fields for each body parameter.

TO DO: Don't use the presence of schema:encodingType and absence of oplwebsrv:parameterType "body" parameters to imply opaque content will be supplied using body_data_src_url (REST API) or -d, --data_url <data_url> (CLI). Make this explicit instead through a new property for a schema:EntryPoint:

oplwebsrv:bodyDataSrc "url" | "literal"