Page History

...

1. Username---*Present in RDF as well, this is the common key.  Since it is the permanent description of a user this is **{*}immutable*.
2. Password---Only in RDBMS.
3. Membership in Superuser role.  No other roles.

...

token---URI of the edit token. It has no meaning other than its use in an update transaction. This is the last edit token created (and not yet "used up" by an update) on this instance; or else a new one that was created if there wasn't one available.
created---literal timestamp at which the token was created. It may be useful to display the date to the user if there was an existing token of recent vintage.
creator---URI of the user who created the token
new---boolean literal that is true if this the gettoken operation created a new token. when When false, taht it means the token already existed, which indicates there MAY already be another user's update in progress which might and that update may be in conflict with yours. (see the created and creator values)
creatorLabel---rdfs:label--\ of the creator, if available.

Access:
Requires ADD access to the either the instance itself or the its home named graph if the insert argument was given , and REMOVE access on the instance or the graph if the delete argument was given. When action=create, requires READ access on an appropriate Workflow Transition - , out of the New state.

We may eventually decide to implement a quota on the count of statements that may be added or deleted, as a protection against DOS attacks and runaway clients.

SPARQL Protocol Endpoint (/sparql)

This servlet is a complete implementation of the standard SPARQL Protocol, implemented according to the description in http://www.w3.org/TR/2008/REC-rdf-sparql-protocol-20080115/. It also extends the protocol to support specific features of the repository REST API, such as views and workspaces.

The most significant departure from the "standard" is the treatment of the dataset clauses in the SPARQL query language. Sesame's query engine ignores any dataset specified in the query if an explicit dataset is supplied in the API call. This SPARQL endpoint will always supply an explicit dataset in order to enforce access control: the dataset determines which named graphs the query is allowed to "see". If the HTTP request asks for certain named graphs by URI, they will be included in the dataset so long as the current user has read access to them.

Matching or restricting by Named Graph: If you want to use the GRAPH keyword as described in section 8.3 of the SPARQL Specification, Sesame's implementation requires named graphs (context) to be present in both the default-uri and named-uri lists of the dataset. The view and workspace abstractions manage this automatically, but if you are constructing a dataset yourself be sure to heed this advice if you use GRAPH.

Inferred Statements: The inferred option determines whether inferred statements are included in the query results. Its default is true. This is a nonstandard exstension to the SPARQL protocol.

Character Sets: The SPARQL query document is entered as the value of the HTTP query-argument query in a GET or POST request. When the query is embedded in the URL in a GET request, or in a body of content-type application/x-www-form-urlencoded in a POST, it MUST use the character set of the URL. This is supposed to be ISO Latin-1 (ISO-8859-1) according to the HTTP 1.1 spec, but in practice browsers seem to use UTF-8-encoded Unicode.
If you put multilingual characters in a SPARQL query document, which is perfectly legitimate in literal values, the best way to ensure they are interpreted correctly is to declare the content-type explicitly with a charset parameter. To do this you must send a POST request with the entity body in multipart/form-data format, so that each argument value is encoded as a separate entity. This adds complexity, but it is the best way to ensure your HTTP client conveys the character set identification correctly. Within the entity for the query arg, add the header: Content-Type: text/plain;charset="UTF-8"
If you're using UTF-8. The media type should always be text/plain.

URL: /repository/sparql (GET and POST)

Args:
query---the text of the SPARQL query document.
default graph-uri---add this URI to the list of default graphs in the query dataset, overriding any built-in default. Read access required. Conflicts with other explicit methods of specifying datasets: the *-graph-uri, view, and workspace arguments are all mutually exclusive. Can be specified multiple times to include multiple graphs.
named-graph uri---add this URI to the list of named graphs in the query dataset, overriding any built-in default. Read access required. NOTE: Sesame's query engine does not seem to pay attention to named graphs, just default graphs, so this argument should be deprecated.
format---explicitly names a result format, overriding the default from HTTP content negotiation. Value must be one of the specified MIME type strings. This is a nonstandard extension to the SPARQL Protocol.
view---symbolic name of a pre-packaged set of named graphs presenting a "view" of the data; see secton on Views in the Concepts section above. Conflicts with other explicit methods of specifying datasets: the *-graph-uri, {{view, and workspace arguments are all mutually exclusive. This is a nonstandard extension to the SPARQL Protocol.
workspace---URI of the workspace named graph to take the place of the default graph. Relevant metadata and ontology graphs are included automatically. Conflicts with other explicit methods of specifying datasets: the *-graph-uri, view, and workspace arguments are all mutually exclusive. This is a nonstandard extension to the SPARQL Protocol.
time---sets an explicit time limit on the query, overriding any built-in default. Value is in seconds. This is a nonstandard extension to the SPARQL Protocol.
inferred---boolean arg.  When false, any inferred statements are excluded from the results. The default is true. This is a nonstandard extension to the SPARQL Protocol.

Result:
The HTTP response includes a result document, whose format depends on the requested format and on the type of query: SELECT queries produce tabular results, ASK and DESCRIBE return an RDF graph, and ASK writes a boolean result. See the MIME Types tables above for all the result formats. In the event of a failure, an HTTP error status is returned.

Timeouts: This service imposes a time limit on the query to prevent one requestor from monopolizing server resources with a time-intensive query. The time limit is taken from the first of these sources with a value:

1. The time argument to the service request
2. Configuration option eaglei.repository.sparqlprotocol.max.time
3. The built-in default is 600 seconds (10 min) if nothing is configured.

Also note:

• Any user can override this setting to impose a shorter timeout by giving a value for the nonstandard time argument.
• Only the Administrator can override with a longer timeout.
• If a SPARQL Protocol request cannot be complted within the timeout, it returns an HTTP 413 status (Result too large)

Access:
Requires Read access to all of the named graphs included in the dataset. When workspace or view arg with a dynamic view is supplied, the dataset is automatically constructed to include only readable named graphs out of a set that depends on the chosen view or workspace.. If a set of graphs is explicitly requested, it is an error if any of them are not readable.
Access NOTE: It MAY be desireable to configure the servlets to allow unauthenticated access to /sparql. This would only allow query access to named graphs which the anonymous role can read.

List Named Graphs (/listGraphs)

Returns an enumeration of all named graphs in the repository matching the search criteria, and which the current authenticated user can read. This request is equivalent to a SPARQL tuple query, except it hides the details of internal administrative metadata structures and bypasses most users' lack of read access to that metadata.

This is intended to be used for UI tasks such as populating a pick list of workspaces available to a user creating a new instance.

URL:/repository/listGraphs (GET, POST)

Args:
type=(ontology|metadata|workspace|published|internal)---Restrict results to graphs of the indicated type. Default is to return all graphs, this arg is optional.
format---same as for SPARQL result format, same default (SPARQL XML)

Result:
Response document is a SPARQL tuple result, format determined by the same protocols as for /sparql. It contains the following columns:

namedGraphURI---URI naming the graph
namedGraphLabel}}---Literal, its textual label (rdfs:label) in the admin metadata if any.
typeURI---the URI of its named graph type
typeLabel---String literal, the textual label of the type.
version---Last loaded version, or just value of owl:versionInfo property of the graph's name URI, which is NOT necessarily the correct version, for example, not for the eagle-i data model ontology.
size - count of asserted statements. Note that the inferred graph always shows size of 0. (Long integer literal.)
read--- true if current user has read permission (Boolean literal)
add--- true if user can add statements to this graph.(Boolean literal)
remove--- true if user can remove statements from this graph (Boolean literal)

NOTE on "undocumented" graphs: It is possible that named graphs will get created in the underlying RDF database (Sesame) without the corresponding repository metadata, such as type and label. You can detect an undocumented graph because there will be no value for typeURI. You can use the admin UI to set the type and label, and add access grants.

Access:
Requires authenticated user; reports on all graphs and contexts regardless of your access..

Dump Contents of a Named Graph (/graph - GET)

Creates a serialization of all statements in the indicated graph (or, optionally, all named graphs in the repository). This is typically used for administrative tasks such as backing-up and migrating the contents of the repository.

Non-administrative users should never need to dump an entire graph, and in fact should never use this request. Since the data returned by e.g. a dissemination request on an instance comes from multiple named graphs, the dump of just one graph will be missing some relevant statements.

Request must include either the name argument or all.

URL: /repository/graph (GET)

Args:
format---ps all (accessible) graphs. Format must be one that encodes quads, e.g. TriG or TriX, or an error will occur.
inferred---include inferred statements as well. By default they are left out. This argument does not need a value, it is boolean so just including its name as a query arg will assert it. (SEE WARNING BELOW)

Result:
Output document is the serialization of the selected RDF statements. Any failure returns an appropriate HTTP status.

WARNING: When you dump a graph with the inferred option on, be sure it does NOT get re-loaded into the repository because then the inferred statements will become explicit and will not get re-computed when necessary. It was mainly intended to be used in testing.

Access:
Requires read access on the selected graph(s). When all is specified, non-readable graphs are ignored.
Load Serialized RDF into Named Graph (/graph - POST, PUT)
Import a serialized RDF document into a specific named graph, optionally replacing all previous contents. The repository records some provenance metadata about when and who did the import, and a description of the source material.

If the name parameter is not specified, and the format supports named graphs or quads (e.g. TriG or TriX), then the graph name is taken from the ingested data. This is very dangerous, but is useful for e.g. restoring an entire repository from a backup. It requires administrator role.

The action argument lets you choose whether to add to or replace the graph contents. To remove all contents of a graph, upload an empty serialization in replace mode.

Note on File Format and Character Set: The request specifies the file format and/or character set of the serialized RDF data as a Content-Type value, e.g. text/rdf+n3; charset="ISO-8859-1". The character set defaults to Unicode UTF-8, so if your source data is not in that character set you must declare it. This can be provided in several different places – they are searched in this order of priority, and hte first one found is the only one considered:

format query argument value. This takes precedence because some clients may not allow complete control of the content-type headers.
Content-Type header on the value of the content entity in a POST request.
Content-Type header in the body of a PUT request.

URL: /repository/graph (PUT or POST)

Args:
name=named-graph-URI - Required name of the affected graph. Mutually excluseive with all.
all - loads serialized data into all (accessible) graphs. Format must be one that encodes quads, e.g. TriG or TriX.
action=(add|replace|delete) - Required, determines whether new statements are added to existing contents of the graph, replace the contents, or are deleted from teh graph.
format - MIME type input serialization format, overrides the Content-Type in HTTP protocol.
type=(metadata|ontology|workspace|internal|published) - Keyword representing the type of content in this named graph.
label=text - value for rdfs:label property of the named graph, which appears as its title.
content= - The immediate content of serialized RDF to load into the graph. ONLY used when method is POST, but then it is required.
source=string - The file or URL to record as the source of the data being ingested into the graph. Only applies to add and replace actions. Overrides any filename specified with the content, which would otherwise be recorded as the source identifier. It is recorded as the dcterms:identifier property of the dcterms:source node in the metadata.
sourceModified=dateTimeStamp - last-modified time for the source of data being ingested. Value must be parsed as XSD date-time expression. It is recorded as the dcterms:modified property of the dcterms:source node in the metadata.

Result:
HTTP status indicates success.

Access:
If the graph already exists, requires add access (and remove access action is replace or delete). If there is no existing graph by that name, only the administrator can create a new one. For multi-graph (all) load, requires superuser access.
Logout (/logout)
Destroys any lingering session state and credentials for the current user. Users of shared or public computers need a way to positively end a session so that subsequent users do not get their access to the repository.

NOTE: Beware of this if you are using a Web browser to access the repository – The repository uses HTTP Basic Authentication to identify users. Most web browsers cache the last Basic Authentication credentials for a site and don't offer an easy way to clear it.

For Mozilla Firefox 3, try the Web Developer add-on and select Miscellaneous->Clear Private Data->HTTP Authentication from its menus.

URL: /repository/logout (POST only)

Args: none.

Result:
HTTP status indicates success. Succeeds even if there was no session to destroy.

Access:
Requires a login and established session.