OSDB API for REST-ful Interactions
Contents
- API Reference
- Authentication and Access Control
- Error Reporting
- Services
- Actions
See Also
- OSDB: Home
- OSDB: Configuration Guide
- OSDB: REST API - Console
- OSDB: REST API - Authentication
- OSDB: REST API - Swagger Petstore Example
- OSDB: Access Control
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_description_url - The URL of a resource containing the RDF service description.
- service_moniker - The service ID to associate with the service.
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:
- the raw action output
- a URL encapsulating the action request which executes the action when dereferenced (only for actions using GET)
- RDF generated from the action output
- 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”.
-
query: The parameter is supplied in a query string.
-
header: The parameter is supplied as an HTTP header.
-
uri: The parameter value is a URI.
-
path: The parameter value is a URI path segment.
-
body: Parameter data is supplied in the HTTP request 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:
-
osdb:output_type- Permitted values:
"url_only","generate_rdf","display_rdf"
- Permitted values:
-
osdb:response_format- Permitted values:
- An output MIME type supported directly by the action (these are listed in the “content_types” property of the entry point description returned by the ‘describe action’ method),
- If
"osdb:output_type" : "generate_rdf"is used, an output MIME type supported by a Virtuoso Sponger cartridge, i.e. one of"application/ld+json","text/turtle"or"application/rdf+xml".
- Permitted values:
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&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&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&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&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&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&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 as an opaque unstructured block.
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.
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
The OSDB REST API obtains opaque body content via one of two properties, either osdb:body_data_src_url or osdb:body_data_raw.
osdb:body_data_src_url specifies the URL of a resource containing input data for the action. Alternatively, clients can use osdb:body_data_raw to supply the input data directly. One of these parameters must be added by an OSDB client to the JSON parameter object sent to the ‘execute action’ method, alongside any other service-specific or OSDB-specific non-body parameters in the parameter object. Data supplied through osdb:body_data_raw, whether text or binary, must be base64 encoded.
Use of osdb:body_data_raw also requires osdb:body_data_encoding to specify the media type of the data before base64 encoding. osdb:body_data_encoding isn’t required with osdb:body_data_src_url. In this case the media type of the data is determined by the web-accessible resource containing the data.
Examples
Using osdb:body_data_src_url
curl -ik -X POST -H 'Content-Type: application/json' "https://osdb.openlinksw.com/osdb/api/v1/actions/csv_transformer/transform/exec" -d '{ "Content-Location": "http://demo.openlinksw.co.uk/trento/pubs", "osdb:body_data_src_url": "http://ods-qa.openlinksw.com/DAV/home/osdb/pubs.csv", "extractor": "csv", "osdb:response_format": "application/ld+json" }'
For the CSV transformer service description extract above, the parameter object sent to ‘execute action’ will take the form shown by the debug console output below
#execute_action: req.body {
'Content-Location': 'http://demo.openlinksw.co.uk/trento/pubs',
extractor: 'csv',
'osdb:body_data_src_url': 'http://ods-qa.openlinksw.com/DAV/home/osdb/pubs.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.
Using osdb:body_data_raw
curl -ik -X POST -H 'Content-Type: application/json' --data-binary @osdb_csv_transform_req_body.json "https://osdb.openlinksw.com/osdb/api/v1/actions/csv_transformer/transform/exec"
where file osdb_csv_transform_req_body.json contains
{
"Content-Location": "http://demo.openlinksw.co.uk/trento/pubs",
"extractor": "csv",
"osdb:body_data_encoding": "text/csv",
"osdb:response_format": "application/rdf+xml",
"osdb:body_data_raw": "TnIsQ29tdW5lLE ... 6emFubywzMgo="
}
The example curl command results in OSDB’s ‘execute action’ receiving a parameter object of the form
#execute_action: req.body {
'Content-Location': 'http://demo.openlinksw.co.uk/trento/pubs',
extractor: 'csv',
'osdb:body_data_raw': 'TnIsQ29tdW5lLE ... 6emFubywzMgo=',
`osdb:body_data_encoding': 'text/csv',
'osdb:output_type': 'generate_rdf',
'osdb:response_format': 'application/rdf+xml'
}
Note:
The base64 data for this curl example was generated using the base64 command line utility and then pasted into osdb_csv_transform_req_body.json.
$ base64 pubs.csv > pubs.csv.base64
pubs.csv
Nr,Comune,Insegna,Tipo,Frazione,Indirizzo,Civico
1,Andalo,Al Faggio,Ristorante,Andalo,Via Fovo,11
2,Arco,Osteria Il Ritratto,Ristorante-Bar,Arco,Via Ferrera,30
3,Baselga Di Pine,Ai Due Cami,Albergo-Ristorante-Bar,Baselga Di Pine,Via Pontara,352
...
pubs.csv.base64
TnIsQ29tdW5lLEluc2VnbmEsVGlwbyxGcmF6aW9uZSxJb ...
OSDB CLI - Providing body content
The OSDB CLI includes option -d, --data_url <data_url> for specifying the URL of the action’s input data, equivalent to the REST API’s osdb:body_data_src_url parameter. A CLI equivalent to osdb:body_data_raw is not available.
OSDB Client
Target OSDB server: https://osdb.openlinksw.com
Enter a command (or 'help' or 'exit')
osdb> transform -h
Action options:
...
-d, --data_url [data_url]
The URL of a document containing input data for the action.
The data is sent in the HTTP request body exactly as supplied.
-g, --encoding <encoding>
The MIME type of the body data.
Permitted values: text/csv, text/tab-separated-values
...