Accessing Data Using HTTP Protocol

AnzoGraph supports the standard W3C SPARQL 1.1 Protocol and SPARQL 1.1 Graph Store HTTP Protocol for sending and receiving SPARQL requests between client applications and AnzoGraph. Since AnzoGraph adheres to RDF and SPARQL standards, developers do not need to learn a proprietary protocol or query language to incorporate AnzoGraph into their existing graph-based infrastructure. There are thousands of available SPARQL client libraries for querying SPARQL and graph store endpoints. In addition, tutorials, such as Bob DuCharme's weblog, provide helpful information about SPARQL HTTP protocol.

This topic provides information about the AnzoGraph SPARQL and RDF Graph Store endpoints and describes the supported HTTP methods and parameters.

• Endpoint Types and Supported HTTP Methods
• Endpoint Base URLs
• Authentication and HTTP Request Parameters
• Example HTTP Requests

Endpoint Types and Supported HTTP Methods

The table below describes the SPARQL and RDF Graph Store HTTP endpoints. Both of the endpoints can be used to send requests through the AnzoGraph front end or directly to the database (back end).

Endpoint Type	Description
SPARQL	The SPARQL endpoint accepts HTTP GET and POST methods. Use GET to read data from the endpoint (SELECT, ASK, CONSTRUCT, DESCRIBE queries), and use POST to update data via the endpoint (INSERT, INSERT DATA, CREATE, DELETE, DELETE DATA, DROP queries). Update queries must use the POST method, but read-only queries can be submitted using GET or POST.
RDF Graph Store	The RDF graph store endpoint supports create, read, update, and delete (CRUD) operations and enables programmers to work with RDF graphs in a way that is similar to REST-style interfaces. The graph store endpoint supports GET, POST, UPDATE, and DELETE HTTP methods.

Endpoint Base URLs

This base URL that you use to connect to an AnzoGraph endpoint depends on whether you want to connect to the SPARQL endpoint or the RDF Graph Store endpoint. This section provides details about the base URLs for each endpoint:

• SPARQL Endpoint Base URL
• RDF Graph Store Endpoint Base URL

SPARQL Endpoint Base URL

To connect to the AnzoGraph SPARQL endpoint, use the following base URL:

protocol://hostname:port/sparql

The list below describes each of the base URL components:

• protocol is the protocol to use for the connection: http for HTTP protocol or https for SSL protocol.

  SPARQL HTTP or HTTPS protocol can be enabled and disabled via the enable_sparql_protocol and enable_ssl_protocol settings.

• hostname is the DNS name or IP address of the AnzoGraph host server. For clusters, this is the name or IP address of the leader server.
• port is the port number for the endpoint. The port that you specify depends on the protocol and whether the request is sent to the AnzoGraph front end or back end.

  The front end requires that you use Basic Authentication to connect. The back end does not support authentication. Consider whether the client application supports authentication when specifying the port.

  • Front end: If the front end ports were mapped to the default HTTP (80) and HTTPS (443) ports on the local host when the front end was deployed, do not specify a port. If the front end ports were mapped to non-default HTTP and HTTPS ports, specify the appropriate port based on the protocol.
  • Back end: The port is either the HTTP sparql_protocol_port or the HTTPS ssl_protocol_port. By default, the HTTP SPARQL protocol port is 7070, and the HTTPS SSL protocol port is 8256.
• sparql is the endpoint path for the SPARQL endpoint.

For example, the following base URLs connect to the front end HTTP and HTTPS SPARQL endpoints. Because the ports for this deployment are mapped to the default HTTP and HTTPS ports on the local host, the port does not need to be specified in the URL:

http://10.100.10.20/sparql

https://10.100.10.20/sparql

The example URLs below connect to the back end HTTP and HTTPS SPARQL endpoints. In the examples, AnzoGraph is using the default SPARQL protocol and SSL protocol ports:

http://10.100.10.20:7070/sparql

https://10.100.10.20:8256/sparql

RDF Graph Store Endpoint Base URL

To connect to the AnzoGraph RDF graph store endpoint, use the following base URL:

protocol://hostname:port/endpoint_path

The list below describes each of the base URL components:

• protocol is the protocol to use for the connection: http for HTTP protocol or https for SSL protocol.

  SPARQL HTTP or HTTPS protocol can be enabled and disabled via the enable_sparql_protocol and enable_ssl_protocol settings.

• hostname is the DNS name or IP address of the AnzoGraph host server. For clusters, this is the name or IP address of the leader server.
• port is the port number for the endpoint. The port that you specify depends on the protocol and whether the request is sent to the AnzoGraph front end or back end.

  The front end requires that you use Basic Authentication to connect. The back end does not support authentication. Consider whether the client application supports authentication when specifying the port.

  • Front end: If the front end ports were mapped to the default HTTP (80) and HTTPS (443) ports on the local host when the front end was deployed, do not specify a port. If the front end ports were mapped to non-default HTTP and HTTPS ports, specify the appropriate port based on the protocol.
  • Back end: The port is either the HTTP sparql_protocol_port or the HTTPS ssl_protocol_port. By default, the HTTP SPARQL protocol port is 7070, and the HTTPS SSL protocol port is 8256.
• endpoint_path is the path for the RDF graph store endpoint. The path that you specify depends on whether the request is being sent to the front end or back end:
  • Front end: The front end path is data.
  • Back end: The back end path is rdf-graph-store.

For example, the following base URLs connect to the front end HTTP and HTTPS RDF graph store endpoints. Because the ports for this deployment are mapped to the default HTTP and HTTPS ports on the local host, the port does not need to be specified in the URL:

http://10.100.10.20/data

https://10.100.10.20/data

The example URLs below connect to the back end HTTP and HTTPS RDF graph store endpoints. In the examples, AnzoGraph is using the default SPARQL protocol and SSL protocol ports:

http://10.100.10.20:7070/rdf-graph-store

https://10.100.10.20:8256/rdf-graph-store

Authentication and HTTP Request Parameters

The AnzoGraph front end SPARQL and RDF Graph Store endpoints require that you use Basic Authentication. The default credentials for the front end are Username:admin and Password:Passw0rd1. The back end does not require user authentication.

For information about the supported HTTP header and request parameters for the SPARQL endpoint, see the SPARQL 1.1 Protocol specification. For information about HTTP parameters for the RDF graph store endpoint, see the SPARQL 1.1 Graph Store HTTP Protocol specification.

Example HTTP Requests

This section includes sample HTTP requests using different languages:

• cURL Example
• Python Example

cURL Example

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 HTTP requests:

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

For example, the following cURL request is sent to the front end SPARQL endpoint and returns 10 triples from the sample Tickit graph. The statement returns results in CSV format:

curl https://10.10.10.100/sparql --insecure -u admin:Passw0rd1 -H "Accept: text/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

The following cURL request sent to the back end SPARQL endpoint (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 example 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 admin:Passw0rd1 --data-urlencode
query@/home/user/queries/sales_totals.rq

Python Example

You can also use the AnzoGraph SPARQL endpoint URL to execute SPARQL commands from programs such as Python or Javascript. AnzoGraph provides a Python library file, azg3.py, located in the AnzoGraph <install_path>/lib/py_modules directory, to help you get started using Python to run SPARQL queries. The following link lets you take a look at the content of the Python library file provided with AnzoGraph:

azg3.py

The azg3.py module includes two functions for executing AnzoGraph SPARQL query statements:

azg3.run_query(sparql_endpoint, SPARQL_query_string [, format]) 

Runs the specified SPARQL query "query_string" at the SPARQL endpoint host location "sparql_endpoint". By default, this function returns the results as a Python dictionary map in the SPARQL1.1 results format (see https://www.w3.org/TR/sparql11-results-json). To output results using an alternate "raw string" format, you may also specify a different format, with possible format options xml, json, or csv.

azg3.create_dataframe(sparql_endpoint, SPARQL_query_string)

Runs the specified SPARQL query "query_string" on the SPARQL endpoint host "sparql_endpoint". This function returns results as a Pandas data frame object, for example:

df = azg3.create_dataframe("10.102.0.56:7070" , "SELECT... ")

To execute SPARQL queries from Python applications, you need to first have installed Python 3, and the NumPy and Pandas libraries, on your client machine with network access to a deployed AnzoGraph environment. The easiest way to install these packages is to install the Anaconda distribution, which automatically installs Python 3 along with a number of different scientific and data analysis packages (including NumPy and Pandas) that may be helpful in performing analytic queries and calculations on various types of data. (See https://www.anaconda.com/distribution for information about installing the Anaconda distribution.)

After creating the Python environment on a client machine:

1. Copy the <install_path>/lib/py_modules directory to your client machine:

   $HOME/py_modules

2. Update your PYTHONPATH environment variable setting to include the Python module location:

   export PYTHONPATH=$HOME/py_modules

   If you already have PYTHONPATH defined on your computer, copy the Python az3.py library file there instead.

For any Python programs in which you want to perform SPARQL queries, you will need to import the azg3.py library file. You can then use either of the two functions, azg3.run_query or azg3.create_dataframe to specify the SPARQL query you want to execute, as well as the location of the AnzoGraph server where the query will be run, for example, "10.102.0.56:7070".