Access the HTTP Client Interface

In addition to the SPARQL HTTP(S) endpoint that enables users to send SPARQL queries to Anzo over HTTP, Anzo provides an HTTP(S) servlet that can be used to invoke Anzo client operations over HTTP. The client servlet enables external systems to interact with Anzo semantic services as well as custom services. It also enables remote servers to interact with Anzo without needing the Anzo command line interface.

HTTP Methods and Options

The Anzo client servlet accepts HTTP GET and POST methods. GET is used for operations that retrieve data, and POST is used for update operations that add or remove data. Update operations must use the POST method, and read operations can be submitted using GET or POST.

Client Servlet Base URL

Use the following URL to access Anzo services via the HTTP client servlet. The table below describes each URL component:

<protocol>://<hostname>:<port>/anzoclient/<client_operation>

For example:

https://10.100.10.20:8443/anzoclient/call
Option Description
protocol The protocol to use for the connection: http for HTTP protocol or https for SSL protocol.
hostname The DNS name or IP address of the Anzo server.
port The port for the endpoint. The port that you specify depends on the protocol that you choose. By default, the HTTP port is 80 and the HTTPS port is 443. To view the ports that are configured for your Anzo instance, see Server Settings in the Administration menu.
anzoclient Required keyword for the client servlet.
client_operation The type of Anzo client operation to invoke. The list below provides an overview of the supported operation types. For more information about the operations, see Client Operations below.
  • call: Invokes the semantic service operation identified by the URI provided in the request (analogous to the anzo call CLI command)
  • add: Imports the specified statements to Anzo (analogous to the anzo import CLI command)
  • remove: Removes the specified statements from Anzo (analogous to the anzo update -r CLI command)
  • get: Gets the specified named graph from Anzo (analogous to the anzo get CLI command)
  • find: Finds the statements in Anzo that match the specified pattern (analogous to the anzo find CLI command)

Client Operations

This section provides usage information and examples for each of the Anzo client operations.

Call

The call operation invokes a semantic service. Identify the service to call by providing the URI for the service in the request header. The call operation is supported with HTTP GET and POST methods. When including RDF data as input to the service, the request must use the POST method.

Call Header Options

Call operations support the following header parameters. Only the uri parameter is required:

  • uri: Required parameter that specifies the URI of the semantic service to invoke.
  • mimeType, Content-Type, or format: Include one of these optional parameters to specify the MIME type for the RDF serialization used in the request body as well as the response from the service. The default type is application/json if the header does not specify the format. For more information about the supported RDF serialization types, see Format Options.

Call Body Options

If the call operation supplies data as input to the service, include the data in the request body. The data must be serialized as specified in the request header, or application/json if the header does not specify a serialization type.

Call Examples

The following cURL example uses a GET call to invoke a health check service. 

curl https://10.100.10.20:8443/anzoclient/call \
  --user sysadmin:123 \
  --header 'uri: http://www.csi.com/service/genericIngestManager#healthCheck'

The example below uses a POST call to invoke a service operation. The call passes in a request data set that is serialized as RDF JSON.

curl https://10.100.10.20:8443/anzoclient/call \
  --header 'Content-Type: application/json' \
  --user sysadmin:123 \
  --header 'uri: http://someServiceURI#someOperation' \
  --data '{"subject" : {"objectType": "uri" ,"value" : "urn://test"},
           "predicate" : "urn://predicate",
           "object" : {"objectType": "uri" ,"value" : "urn://object"},
           "namedGraphUri" : "urn://ng"}'

The example below uses a POST call to invoke a service operation. The call passes in a request data set that is serialized as TriG.

curl https://10.100.10.20:8443/anzoclient/call \
  --header 'Content-Type: application/x-trig' \
  --user sysadmin:123 \
  --header 'uri: http://www.csi.com/service/genericIngestManager#healthCheck'
  --data '<urn://ng> { <urn://test> <urn://predicate> <urn://object> .}'

Add

The add operation adds statements to the Anzo graphstore. Add is supported with the HTTP POST method. The header can include mimeType, Content-Type, or format to specify the MIME type for the RDF serialization used in the request body as well as the response from the service. The default type is application/json if the header does not specify the format. For more information about the supported RDF serialization types, see Format Options. The request body includes the statements to add.

Add Examples

The following example add operation uses cURL to issue a POST call to add a statement to the graphstore. The statement is specified in Anzo JSON RDF serialization format.

curl https://10.100.10.20:8443/anzoclient/add \
  --user sysadmin:123 \
  --data '{"subject" : {"objectType": "uri" ,"value" : "urn://test"},
           "predicate" : "urn://predicate",
           "object" : {"objectType": "uri" ,"value" : "urn://object"},
           "namedGraphUri" : "urn://ng"}'

Remove

The remove operation deletes statements from the Anzo graphstore. Remove is supported with the HTTP POST method. The header can include mimeType, Content-Type, or format to specify the MIME type for the RDF serialization used in the request body as well as the response from the service. The default type is application/json if the header does not specify the format. For more information about the supported RDF serialization types, see Format Options. The request body specifies the statements to remove.

Remove Examples

The following example remove operation uses cURL to issue a POST call to remove a statement from the graphstore. The statement is specified in Anzo JSON RDF serialization format.

curl https://10.100.10.20:8443/anzoclient/remove \
  --user sysadmin:123 \
  --data '{"subject" : {"objectType": "uri" ,"value" : "urn://test"},
           "predicate" : "urn://predicate",
           "object" : {"objectType": "uri" ,"value" : "urn://object"},
           "namedGraphUri" : "urn://ng"}'

Get

The get operation retrieves a named graph from the Anzo graphstore. The get operation is supported with HTTP GET and POST methods. The named graph URI that contains the contents to retrieve can be included as a query parameter or as a uri parameter in the request body. The get operation also returns the metadata graph, which is equivalent to running anzo get -m <named_graph_uri> with the Anzo admin CLI. The header can include mimeType, Content-Type, or format to specify the MIME type for the RDF serialization used to format the response from the service. The default type is application/json if the header does not specify the format.

Get Examples

The following example get operation uses cURL to retrieve the contents of a named graph.

curl -k -XPOST https://10.100.10.20:8443/anzoclient/get --user sysadmin:123
     --data-urlencode
     "uri=http://cambridgesemantics.com/Graphmart/9da211618a15476daa10cead2292d8e7"

This example uses Python with requests:

import requests

url = "https://10.100.10.20:8443/anzoclient/get"
data = {"uri": "http://cambridgesemantics.com/Graphmart/9da211618a15476daa10cead2292d8e7"}
username = "sysadmin"
password = "123"
r = requests.post(url, data=data, auth=(username, password), verify=False)
print (r.text

Find

The find operation finds the statements in the graphstore that match the pattern that is specified in the request. The find operation is supported with HTTP GET and POST methods. Header options are not applicable. The list below describes each of the supported parameters. These parameters can be included as query parameters in the URL or as parameters in the request body:

  • graph: The named graph URI for the find pattern.
  • sub: The subject of the find pattern.
  • pred: The predicate of the find pattern.
  • lit: The object of the find pattern if that object is a literal value.
  • uri: The object URI of the find pattern if that object is a URI.
  • type: If the object is a literal, this parameter can be used to specify the data type of the literal value.
  • lang: If the object is a literal, this parameter can be used to specify the language of the literal value.

Results returned by the find operation are in Anzo JSON RDF serialization format. See Anzo JSON RDF Serialization below for details.

Find Examples

The following example find operation (using the GET HTTP method) finds all of the statements in the graphstore with predicate http://w3.org/1999/02/22-rdf-syntax-ns#type and an object URI of http://cambridgesemantics.com/ontologies/2009/05/LinkedData#LinkedDataSet. The parameters are specified as query parameters in the URL.

curl https://10.100.10.20:8443/anzoclient/find?pred=http://www.w3.org/1999/02/22-rdf-syntax-ns%23type&amp;uri=http://cambridgesemantics.com/ontologies/2009/05/LinkedData%23LinkedDataSet' \
  --user sysadmin:123

The example below finds the same statements but issues a POST call. The URL-encoded parameters are specified in the request body.

curl https://10.100.10.20:8443/anzoclient/find \
  --user sysadmin:123
  --data 'pred=http%3A%2F%2Fwww.w3.org%2F1999%2F02%2F22-rdf-syntax-ns%23type&uri=http%3A%2F%2Fcambridgesemantics.com%2Fontologies%2F2009%2F05%2FLinkedData%23LinkedDataSet'

Anzo JSON RDF Serialization

Anzo's JSON RDF serialization standard is straightforward but differs from the common public JSON RDF serialization standards. In Anzo JSON serialization format, a set of statements (quads) are represented as an array of JSON objects. Each JSON object (statement) is defined as a key/value pair, where the key specifies the component of the statement, i.e., the subject, predicate, object, or namedGraphUri. Depending on the component, properties such as the component's value and data type are specified in nested objects.

The following example array shows Anzo's JSON serialization. The list below the example describes the structure. 

[  
  {
    "subject" : {
        "objectType": "uri" ,
        "value" : "urn://test"
    },
    "predicate" : "urn://predicate",
    "object" : {
        "objectType": "uri" ,
        "value" : "urn://object"
    },
    "namedGraphUri" : "urn://ng"
    },
  {
    "subject" : {
        "objectType": "uri" ,
        "value" : "urn://test"
    },
    "predicate" : "urn://predicate2",
    "object" : {
        "objectType": "literal" ,
        "value" : "test literal",
        "dataType" : "http://www.w3.org/2001/XMLSchema#string"
    },
    "namedGraphUri" : "urn://ng"
  }
]
  • subject is a JSON object with two properties:
    • objectType: The resource type of the subject value. This is either a "uri" or "bnode" (blank node).
    • value: The blank node value or a string literal that specifies the URI.
  • predicate is a string literal that specifies the predicate URI.
  • object is a JSON object with two required properties and two optional properties:
    • objectType: Required property that specifies whether the object is a "uri," "literal," or "bnode."
    • value: Required property that specifies the string representation of the object value.
    • dataType: Optional property for use if the objectType is "literal." This property describes the data type of the literal value. It is a string literal of the XSD data type URI. For example: "http://www.w3.org/2001/XMLSchema#string"
    • language:Optional property for use if the objectType is "literal." This property describes the language of the literal value.
  • namedGraphUri is a string literal that specifies the named graph URI.