Using AnzoGraph APIs

Since AnzoGraph adheres to the W3C RDF and SPARQL 1.1 standards, developers do not need to learn a proprietary query language to incorporate AnzoGraph into their existing infrastructure of products that support standard graph application program interface (API) communication protocols. AnzoGraph provides a REST API that uses the standard SPARQL 1.1 Protocol on HTTP/S for sending and receiving SPARQL queries between client applications and the database. There are thousands of available SPARQL client libraries for querying SPARQL endpoints. In addition, tutorials, such as Bob DuCharme's weblog, provide helpful information about SPARQL HTTP protocol.

In addition to the standard SPARQL protocol, AnzoGraph offers a secure SPARQL HTTPS endpoint for encrypted SSL communication as well as a gRPC endpoint for authenticated and encrypted communication.

Note: AnzoGraph also provides Bolt protocol support for direct execution of Cypher-based commands and queries, either from a Cypher-based CLI (AZGBOLT) or from other Cypher-based applications that use the Bolt protocol. For more information, see Using the Cypher Command Line Interface (AZGBOLT) and Cypher and SPARQL Support for Bolt Protocol Applications.

Connecting to AnzoGraph Endpoints

To connect to AnzoGraph you can specify the following endpoint URL:

protocol://hostname:port/sparql [SPARQL statement options]

The following table describes each of the endpoint URL options:

Option Description
protocol The protocol to use for the connection: http for SPARQL HTTP protocol or https for SSL protocol.

Note: Users can enable or disable SPARQL HTTP or HTTPS protocol via the enable_sparql_protocol and enable_ssl_protocol settings.

hostname The DNS name or IP address of the AnzoGraph host server or the leader server in a multi-server deployment.
port The port for the endpoint. The port that you include depends on the protocol that you chose. By default, the HTTP port (sparql_protocol_port) is 7070, the HTTPS port (ssl_protocol_port) is 8256.

For example, to use the HTTP/S REST API for sending and receiving SPARQL queries and results between client applications and the AnzoGraph, you could enter the following URL:

http://hostname/sparql [SPARQL statement options]

or

https://hostname/sparql [SPARQL statement options]

Each AnzoGraph server presents a unique IP address with an HTTP GET/POST interface.

Specifying SPARQL Endpoint Statement Options

In addition to the AnzoGraph endpoint URL, the following table describes SPARQL statement options that are available with different deployment options:

Option Description
--insecure With AWS CloudFormation, Docker, and Kubernetes deployments, you can specify this optional argument to query the AnzoGraph HTTPS endpoint with the default AnzoGraph certificate.
-u username With AWS CloudFormation, Docker, and Kubernetes deployments, you can specify this optional argument which is the user name for AnzoGraph. You can also specify -u username:password.
-H "header_argument" Optional argument that specifies the format for query results. AnzoGraph supports returning SPARQL results in XML, JSON, or CSV formats. To specify a format, use one of the following header arguments:
  • Accept: xml
  • Accept: json
  • Accept: csv

For tarball deployments, specify header arguments as follows:

  • Accept: application/sparql-results+xml
  • Accept: application/sparql-results+json
  • Accept: application/sparql-results+csv

If you exclude the header argument, AnzoGraph returns results in XML format.

--data-urlencode Performs URL encoding on the query.
"query=query_text" Query_text is the query to run against AnzoGraph. Include query= and enclose the entire statement in quotation marks.
query@file.rq Use the query@ notation without quotation marks to run queries from a file. Include the path and filename for the file.

AnzoGraph Endpoint Query Example using cURL

The following example, using the curl command, shows how you can specify a SPARQL query using AnzoGraph endpoint URLs. To query AnzoGraph using cURL, the queries must be URL encoded. The command statement below shows the general syntax you could use to make curl requests to AnzoGraph

curl AZG_endpoint [ --insecure ] -u username [ -H "header_argument" ]
--data-urlencode "query=query_text" | query@file.rq  '

For example, with AWS CloudFormation, Docker, and Kubernetes deployments, the following cURL statement queries the AnzoGraph endpoint to return 10 triples from the sample Tickit data set. The statement returns results in CSV format:

curl https://10.10.10.100/sparql --insecure -u query:userpass1 -H "Accept: csv"
--data-urlencode "query=select ?s ?p ?o from <tickit> where {?s ?p ?o} order by ?p limit 10"
s,p,o
person39003,birthday,1986-09-12
person33946,birthday,1988-12-24
person10199,birthday,1953-04-13
person41860,birthday,1976-06-25
person13789,birthday,1981-06-23
person30637,birthday,1978-11-26
person38857,birthday,1960-01-07
person24661,birthday,1992-11-21
person17029,birthday,1993-03-08
person43904,birthday,1962-01-06

With RHEL/Centos Tarball deployments, the following cURL statement (without the insecure or username options) would return the same result.

curl http://10.10.10.100:7070/sparql -H "Accept: application/sparql-results+csv"
--data-urlencode "query=select ?s ?p ?o from <tickit> where {?s ?p ?o} order by ?p limit 10"

This following example, for AWS CloudFormation, Docker, and Kubernetes deployments, uses cURL to run a query contained in a file. Since the statement does not include a header argument, AnzoGraph returns results in XML format:

curl https://10.10.10.100/sparql --insecure -u query:userpass1 --data-urlencode
query@/home/user/queries/sales_totals.rq

With RHEL/Centos Tarball deployments, the following cURL statement would return the same result.

curl http://10.10.10.100:7070/sparql --data-urlencode
query@/home/user/queries/sales_totals.rq