== HTTP server ==

4store includes a SPARQL HTTP protocol server, which can answer SPARQL queries using the standard SPARQL HTTP query protocol among other features.

== Running ==

{{{
4s-httpd -p 8000 demo
}}}

This starts a server on TCP port 8000 which answers queries for the 4store KB named demo. If you have several 4store KBs they will need to run on separate ports.

''N.B.'' When you run a 4s-httpd and connect it to a 4store backend you will no longer be able to use the 4s- command line tools. You can however use [http://github.com/tialaramex/sparql-query/ sparql-query] (or any other SPARQL client) to issue queries, and curl to add/remove graphs (see below).

== Querying ==

Once the above example server is running you can see an overview page from a web browser at

{{{
http://localhost:8000/status/
}}}

and the SPARQL endpoint is at

{{{
http://localhost:8000/sparql/
}}}

With an HTML interface at

{{{
http://localhost:8000/test/
}}}

You can use [http://github.com/tialaramex/sparql-query sparql-query] to query the SPARQL server on the command line.

=== Soft Limits ===

By default 4store gives a soft limit of about 1000, this prevents the query engine from doing too much work on any one query. You can change this value using a CGI argument {{{soft-limit}}}, setting it to -1 will disable the soft limit altogether.

== Updates ==

You can send SPARQL Update 1.1 requests to {{{http://localhost:8000/update/}}} or the appropriate URL for your settings.

Updates must be send as POST reuqests, to the /update/ endpoint, and the request is sent with the update= CGI parameter, e.g.

{{{
curl -i -d 'update=INSERT+DATA+{+GRAPH+<http://example.com/G>+{+<http://example.com/s>+<http://example.com/p>+"o"+}+}' http://localhost:8000/update/
}}}

Which will send the SPARQL Update request

{{{
INSERT DATA { GRAPH <http://example.com/G> { <http://example.com/s> <http://example.com/p> "o" } }
}}}

== Adding and Removing Data ==

You can add and remove RDF graphs using a RESTful interface. The RESTful update endpoint is on {{{/data/}}}, so by default the URI is {{{http://localhost:8000/data/}}}.

=== Removing data with DELETE ===

You can delete graphs using the DELETE HTTP verb. eg.

{{{
curl -X DELETE 'http://localhost:8000/data/http://example.com/data'
}}}

or the SPARQL 1.1 standard syntax (available in more recent versions of 4store), which is:

{{{
curl -X DELETE 'http://localhost:8000/data/?graph=http%3A%2F%2Fexample.com%2Fdata'
}}}

=== Replace data with PUT ===

Data can be replaced using the {{{PUT}}} verb. If you want the model URI (SPARQL graph) to be a sub-URI of the SPARQL endpoint then it's easy:

{{{
curl -T file.rdf 'http://localhost:8000/data/file.rdf'
}}}

will use PUT to write/replace the graph http://localhost:8000/data/file.rdf in the store.

If you want to write to an arbitrary graph URI then you can concatenate the SPARQL endpoint URI and the graph URI, eg. if you want to write to http://example.com/data you can use:

{{{
curl -T file.rdf 'http://localhost:8000/data/http://example.com/data'
}}}

The server will attempt to guess the content type of the data PUT, but you can specify a MIME type directly with the Content-Type header, eg:

{{{
curl -T file.rdf -H 'Content-Type: application/x-turtle' 'http://localhost:8000/data/data.rdf'
}}}

If using an HTTP library directly then you can just connect to localhost:8000 and PUT to the end URI directly, eg:

{{{
PUT http://example.com/data HTTP/1.0
...
}}}

the above feature is just for compatibility with clients with limited expressivity.

=== Append data with POST ===

If you wish to add data to a graph then you can use the POST verb. POST requests must be sent to the {{{/data/}}} endpoint to distinguish them from SPARQL/Query requests. 

The POST arguments used are {{{graph}}}, {{{data}}}, and {{{mime-type}}}.

{{{graph}}} contains the graph URI to append data to, {{{data}}} contains the RDF syntax bytes, and {{{mime-type}}} the MIME type of the POSTed data.

{{{
curl -d 'data=%3Chttp%3A%2F%2Fexample.com%2Fperson%2F1234%23person%3E+%3Chttp%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2Fname%3E+%22John+Doe%22+.&graph=http%3A%2F%2Fexample.com%2Fgraph3&mime-type=application/x-turtle' http://localhost:8888/data/
}}}

Which posts the following turtle :

{{{
<http://example.com/person/1234#person> <http://xmlns.com/foaf/0.1/name> "John Doe" .
}}}

To the following model : 
{{{
http://example.com/graph3
}}}

With the following mime-type : 

{{{
application/x-turtle
}}}

To POST the contents of a file to a given graph URI could can use the following incantation of curl :

{{{
curl --data-urlencode data@foo.ttl -d 'graph=http%3A%2F%2Fexample.com%2Fgraph3' -d 'mime-type=application/x-turtle' http://localhost:8888/data/
}}}

Where the notation '--data-urlencode data@foo.ttl' means url-encode the contents of the file 'foo.ttl' and add it to the POST variable 'data'.

Note that, the values POSTed need to be URI encoded.

== Shutting Down ==

If you want to stop the {{{4s-httpd}}} you have to kill it, there will typically be two processes per KB running, so if there's only one KB running you can do {{{killall 4s-httpd}}} to shut it down.

It is safe to kill {{{4s-httpd}}} as long as you don't use -9.

== Config File ==

From version 1.1.2 4s-httpd supports a config file in {{{/etc/4store.conf}}}, there's an example below:

{{{
[default]
        unsafe = true           # enable LOAD etc. (default is disabled)
        cors = true             # enable CORS (default is disabled)

[test]
        port = 8888             # HTTP port number (default is 8080)
        default-graph = false   # default graph = union of named graphs (default)
        soft-limit = 0          # disable soft limit
        opt-level = 3           # enable all optimisations (default)
}}}

This means that all HTTP servers will allow unsafe operations, and enable CORS, and the "test" KB will start on port 8888, have a default query graph, and have the "soft limiting" disabled. Note that if you have a KB called "default" then you can't override settings for it.

== See Also ==

   GraphAccessControl