Inav the Terrible [sic]

1. The Resource

The graph must be represented by a deferenceable URI. In all our examples, this will be http://example.net/data.rdf. This URI will probably point to a CGI script or similar on the example.net web server, though the exact technology used is beyond the scope of this document. What is important is that is behaves in different ways depending on the method used in HTTP requests to it.

2. The Behaviours

@@TODO: Might be good to have a method to remove individual triples from the graph, though this can be achieved using a combination of GET and PUT. Possibly use PROPPATCH with a SPARQL query which returns a list of triples to be removed? Or possibly include a special HTTP header on POST requests (e.g. X-Remove) including some kind of instruction to remove triples before they're added.

2.1. GET

The server must respond with an HTTP 200 status and the full contents of the graph. This must be delivered using a media type acceptable to the client, which should be determined by the HTTP Accept header of the request. Example formats which may be acceptable include RDF/XML, Turtle and XHTML+RDFa. If no other format is acceptable, the response should be sent as N-Triples with a Content-Type header of text/plain; charset=us-ascii.

As an exception to the HTTP 200 rule above, the server may implement proper support for HTTP 304 Not Modified.

2.2. POST

The server should look at the posted data and parse it into RDF triples according to the Content-Type header of the request. These may be either merged into the existing graph, or placed into a moderation queue to be merged later.

If the server supports SPARQL/Update and the request Content-Type is application/sparql-query, then it may use the posted data as a query.

The server must then respond with one of the following HTTP status codes:

• 200 OK: if the triples have been either accepted into a queue or immediately merged.
• 401 Unauthorized: if the client attempting to update the graph is not allowed to. (See Security section.)
• 415 Unsupported Media Type: if the Content-Type header specified was not a format understood by the server.
• 500 Internal Service Error: if any other error occurs.

For HTTP 200 responses, the response body should then be as per GET requests, though it should reflect the new state of the graph.

For other response codes, no particular response body is mandated, though a description of the problem would probably be helpful.

@@TODO: What about blank nodes. How can this be done?

2.3. DELETE

The server may delete all triples in the graph and must then respond with one of the following status codes:

• 200 OK: if the graph has been cleared.
• 401 Unauthorized: if the client attempting to clear the graph is not allowed to. (See Security section.)
• 405 Method Not Allowed: if no clients are allowed to clear the graph.
• 500 Internal Service Error: if any other error occurs.

For servers implementing a moderation queue, it is inadvisable to allow this method.

For HTTP 200 responses, the response body should then be as per GET requests, though it should reflect the new state of the graph.

For other response codes, no particular response body is mandated, though a description of the problem would probably be helpful.

2.4. PUT

The server should look at the posted data and parse it into RDF triples according to the Content-Type header of the request. These may be used to entirely replace the existing graph. For servers implementing a moderation queue, it is inadvisable to allow this method.

The server must then respond with one of the following HTTP status codes:

• 200 OK: if the graph has been replaced.
• 401 Unauthorized: if the client attempting to update the graph is not allowed to. (See Security section.)
• 405 Method Not Allowed: if no clients are allowed to replace the graph.
• 500 Internal Service Error: if any other error occurs.

For HTTP 200 responses, the response body should then be as per GET requests, though it should reflect the new state of the graph.

For other response codes, no particular response body is mandated, though a description of the problem would probably be helpful.

3. The Security

Security is considered beyond the scope of this document. Publishers will usually want to include some sort of access control mechanism, but this may be done at the HTTP layer. As Inav is intended to be used by robots, a non-interactive security mechanism is preferred. Some possible solutions include:

• HTTP Basic authentication
• FOAF+SSL
• Cookies

But the possibilities are unlimited.

It is also possible to accept or reject updates based on the contents of the update. e.g. only a certain pre-defined list of predicates is allowed.

4. The Use Cases

4.1. A FOAF Friends List

Alice publishes her profile using FOAF. It includes a list of her friends. Each friend is identified by a URI, but the file also contains certain information about these friends, such as their names, homepages and interests.

Bob is one of Alice's friends and notices that his homepage is listed incorrectly in Alice's FOAF profile. He sends a POST request to update this information. (@@TODO: see? this is why we need to be able to remove individual triples too!)

Alice's server uses FOAF+SSL to determine who is trying to update her profile. The FOAF+SSL process identifies Bob by the same URI that is already listed in her FOAF profile. Alice's access control rules allow for her friends to update any triples where the subject is themself and the predicate is in the FOAF namespace, so immediately Alice's FOAF profile reflects Bob's corrected homepage.

@@TODO: Show this update as a full worked example.

---