[Interface as of 0.4.1, 2010 October 22]
qsac SAC implementation: A SAC is a Semantic Annotation Collection, which allows users or applications to store and share bookmarks, comments, and other annotations. This implementation is a prototype one, which may or may not become the project's main SAC implementation. There are other implementations (loosely) planned. See the project's 'vision' for the overall plan, and the list of user stories for the detailed functionality we expect to add in the future.
The parent of all the SACs in the service. This returns an HTML page listing the available SACs.
/sac
Retrieve human-readable information about the SAC service. The content of the response is not otherwise specified, but it might include things such as the SACs that are available.
This part of the interface is only available in a 'multiSAC', which is a SAC which contains multiple separate SACs. In a standalone SAC this resource might not be nameable.
| {sacName} | The name of the SAC to be operated on |
An individual SAC
/sac/{sacName}
| ?metadata | If the metadata query parameter is present, with any value, then return the SAC's metadata instead of its content. |
Retrieve a SAC or, if the metadata query parameter is present, retrieve the SAC's metadata. The configuration metadata is discussed in the documentation for the PUT action.
The HTTP 'Accept' header may be present in the request, and if so should be one of the representations listed below as success responses.
Return a representation of the RDF content of the SAC.
/sac/{sacName}
| ?query | A URL-encoded SPARQL query. |
Make a SPARQL query against the SAC
The HTTP 'Accept' header may be present in the request, and if so should be one of the representations listed below as success responses.
See the POST SPARQL method for detailed discussion.
The results of the SPARQL query, in the appropriate MIME type for the query
constructand
describequeries); or the string 'yes' or 'no' for SPARQL
askqueries; or an ascii-art table for SPARQL
selectqueries
selectand
askqueries). See SPARQL query results spec
selectqueries)
selectqueries)
/sac/{sacName}
Add a claim to the SAC: Post RDF to a SAC and
get a claim back. The posted RDF – which must have as its
content-type one of the request MIME types listed below – is parsed with the new
claim URI as its base-URI, so it should refer to the claim
itself with <> (in Turtle) or
rdf:about="" (in RDF/XML). The claim URI is
returned in the response's Location header. If there is no
RDF in the request body, that is an error.
For example, the following RDF would be acceptable as a claim:
@prefix skua: <http://myskua.org/claimtypes/1.0/> .
@prefix dc: <http://purl.org/dc/elements/1.1/> .
<> a skua:bookmark;
skua:ref [
a skua:webpage;
skua:url <http://n2.talis.com/wiki/SPARQL_Demo>;
dc:title "SPARQL Demo - N2 wiki";
];
skua:tag "semanticweb", "rdf", "sparql", "tutorial";
skua:time "2008-01-21T18:11:58Z" .
Returns the ID of the created claim in a Location header
Location: | The full URL of the newly-created claim |
/sac/{sacName}
Make a SPARQL query against the SAC. See the SPARQL spec for full documentation.
SPARQL CONSTRUCT and
DESCRIBE queries produce RDF, and so if an
Accept header is present it must be one of the RDF MIME
types below, namely
text/rdf+n3,
application/rdf+xml,
text/turtle or
text/plain (N-triples).
SELECT queries produce a list
of results, and so the result must be one of the
list
types below, namely
application/sparql-results+xml,
text/plain (ascii-art output),
text/csv or
text/tab-separated-values.
ASK queries can produce either of the types
application/sparql-results+xml or
text/plain (containing one of the strings
yes
or no
), with a 200 status if the
query succeeds, irrespective of whether the answer is true
or false.
The results of the SPARQL query, in the appropriate MIME type for the query
/sac/{sacName}
| ?metadata | The changeset can only (at present) be posted to the SAC's {sacName}?metadata URL. |
Update the SAC metadata by posting to the
{sacName}?metadata URL. The content of the
post must abide by (a profile of) an unversioned update in the
Talis Changeset Protocol,
except that (currently) we may have only one ChangeSet per
posting, and each addition and removal must have the
subjectOfChange as its subject.
/sac/{sacName}
Create a SAC: Create a SAC by PUTing metadata to what you have chosen as the new SAC URI -- that is, making a choice for the {sacName} in the URI. If the SAC already exists, you will receive the status code 409 Conflict.
The metadata can be anything, but might
include for example Dublin Core information. The uploaded
RDF is parsed with the new SAC name as its base URI, and so
should refer to the SAC with <> (in Turtle) or
rdf:about="" (in RDF/XML). The metadata can be retrieved at
the URI which is the SAC's name, with a '?metadata' query
suffixed (see above).
As well as documenting the SAC's purpose, the metadata can also be used to configure the SAC.
You must supply at least some metadata for the SAC, or else the SAC will response with an error 400 Bad Request.
For example, the SAC creation metadata might be as simple as the following
@prefix dc: <http://purl.org/dc/elements/1.1/>. <> dc:description "My SAC"; dc:creator "Norman".
The RDF content of the SAC's metadata.
application/rdf+xmlLocation: | The URL of the newly-created SAC (which will be the same as the URL to which this request was posted). |
<>, or the
metadata could not be parsed as RDF./sac/{sacName}
Delete the SAC
The SAC and its contents have been discarded.
| {sacName} | The name of the SAC to be operated on |
| {submodelName} | An identifier for a specific submodel. |
A submodel which is included in the SAC; this will typically be an ontology of domain-specific knowledge. Queries over the SAC include the contents of the submodel as well as the claims.
/sac/{sacName}/{submodelName}
Retrieve the submodel
The RDF representing a submodel
/sac/{sacName}/{submodelName}
Add or overwrite the existing submodel. The content of the message is parsed with the submodel URI as the base URI.
application/rdf+xmlResponse to PUTting a submodel. Return 201 (Created) if the submodel has been written (whether or not it existed before). Return 404 (Not Found) if the claim was not found.
/sac/{sacName}/{submodelName}
Delete the submodel
The SAC and its contents have been discarded.
| {sacName} | The name of the SAC to be operated on |
| {claimid} | An identifier for a specific claim |
An individual claim.
The structure of the claim URIs is described here only in order to document the methods which may be used on those URIs. However you should not rely on this structure, and a SAC service is free to mint claim URIs with a different structure. You do not need to generate claim URIs at any point, and should instead use only the URIs which are returned in the Location header when you create claims as described above.
/sac/{sacName}/_/{claimid}
Retrieve the claim RDF
The RDF representing a claim
/sac/{sacName}/_/{claimid}
Overwrite the existing claim data. As when creating
the claim (see above), you
must refer to the claim itself in the updated claim RDF.
You can do this by explicitly including the claim URI in
the RDF, or more conveniently by referring to the claim
with <> (in Turtle) or
rdf:about="" (in RDF/XML).
application/rdf+xmlResponse to PUTting a claim. Return 204 (No Content) if the claim existed and has been successfully overwritten, 404 (Not Found) if the claim was not found, or 400 (Bad Request) if the updating RDF did not refer to the claim
/sac/{sacName}/_/{claimid}
Delete the claim
The claim has been deleted
Provide version information, including information about what functionality is compiled in.
/version
An individual component within the SAC software
/version/{component}
The component is not present
RDF/XML is the only RDF serialisation which has been fully standard by W3C. See the definition at http://www.w3.org/TR/rdf-syntax-grammar/.
Turtle is a
well-established but still experimental text syntax for RDF. It's
very closely related to Notation3, but without some of that syntax's
non-RDF extensions. The MIME type is not yet registered, but
text/turtle is being requested; Turtle has also been served
with the MIME type application/x-turtle.
Notation-3
is a well-known, but not fully formally specified serialisation
for RDF.
The application/n3 MIME type is recognised but
deprecated (see W3
discussion), since its IANA registration was never completed;
text/rdf+n3 is the preferred MIME type for Notation3.
The SPARQL query language for RDF is defined in http://www.w3.org/TR/rdf-sparql-protocol/.