Overview

This document is intended to be a thorough description of the data repository design, concentrating on its external interfaces.  Its intended audience is implementors of other components that depend on the repository, as well as the repository coders.  It should be kept up to date with any API changes so it can serve as a reference manual.

...

• Named Graphs:
  • dcterms:modified - literal date of last modification, encoded as xsd:dateTime
  • dcterms:contributor ---the URI of the Agent (authenticated user) who last modified it
  • dcterms:source ---description of file or URI last loaded into this NG, if that is how it was created.  This record is used to compare it against the source later to decide whether an updaet is necessary. It is a node (possibly blank node) with the following properties:
    • dcterms:identifier ---the resolvable URI of the resource loaded, most likely a URL in either the file or http scheme.
    • dcterms:modified ---last-modification date of the resource, for later comparison when deciding whether to decache the repository copy of an external file, a literal xsd:dateTime.
• Resource Instance:

  • Wiki Markup
    *dcterms:created* \---literal date when resource was created, encoded as \[xsd:dateTime

    <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="c98b09b14a4f967f-fa7bc2f6-4e1249ad-a11eb603-bbb25a5b290113c4cedf1493"><ac:plain-text-body><![CDATA[

    [http://www.google.com/url?q=http%3A%2F%2Fwww.w3.org%2FTR%2Fxmlschema-2%2F%23dateTime&sa=D&sntz=1&usg=AFrqEzfRDUuCfWjkGIj5ZuqOGGVPGBo7ZQ]]

    ]]></ac:plain-text-body></ac:structured-macro>

    • Set automatically by the Repository.
  • dcterms:creator ---the URI of the Agent (should be an auth'd user) who created teh instance.
    • The true meaning is the user who authored the data in the inital version of tihs instance.
    • Usually, this is the same as the user directly responsible for creating the instance.
    • However, when a different user uploads e.g. a spreadsheet created by other RNAVs, the Repository user is a mediator. The actual value of dcterms:creator comes from the uploaded data.
  • (optional) dcterms:mediator - ONLY when dcterms:creator does not refer to the authenticated user who created the data, this is the URI of the Agent (authenticated user) who created this instance in the Repository.
    • Set automatically by the Repository.

  • Wiki Markup
    *dcterms:modified* \---literal date when resource was last modified, encoded as \[xsd:dateTime

    <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="63806371d537e57b-0b176f0a-41f14b0b-9cfaa40c-4773285efb63c40e5013454d"><ac:plain-text-body><![CDATA[

    [http://www.google.com/url?q=http%3A%2F%2Fwww.w3.org%2FTR%2Fxmlschema-2%2F%23dateTime&sa=D&sntz=1&usg=AFrqEzfRDUuCfWjkGIj5ZuqOGGVPGBo7ZQ]]

    ]]></ac:plain-text-body></ac:structured-macro>

    • Set automatically by the Repository.
  • dcterms:contributor ---the URI of the Agent (authenticated user) who last modified this instance.
    • Set automatically by the Repository.

...

...

Boolean Query Result Serialization formats:

Identify and/or "Create" Current User (/whoami)

Returns This request returns a tabular report on the current authenticated user's identity, to e.g. compose a friendly display in a Web UI. This is really just simply a SPARQL query wrapped in a servlet to hide the details of the internal data.

This request can also function as a "login" mechanism to establish a session and cache authentication, while at the same time getting the user's displayable name to show in the UI.

Subtle Alternate Function: Note that the POST form of this request has a separate function when create=true: It creates the RDF metadata for a login user account. Normally this is only done as part of the initial bootstrap procedure, by the finish-install.sh script. When users are created through the Admin UI or /import their RDF metadata is created automatically.

NOTE: Perhaps it would be better to implement this as a redirect to the resolvable URI for the person, which would then yield a description compatible with the FOAF standard. That's how the Semantic Web wants us to manage it.

URL: /repository/whoami (GET, POST)

Args:
format- same --Same as for SPARQL result format, same default (SPARQL XML)
create=(true|false) - when When true, invokes alternate function of this service to create RDF metadata for current user (see explanation above).
firstname=text---ONLY when create=true, the first name value of the created User instance (optional).
lastname=text---ONLY when create=true, the last name value of the created User instance(optional).
mbox=text---ONLY when create=true, the mbox value of the created User instance(optional).

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

1. uri---resolvable URI of the :Agent instance for this person if any (see below).
2. username---short user name as given to the login process

...

1. firstnamefirst---(given) name, and middle names if any
2. lastname---user's last (family) name
3. mbox---user's email address

Note that the last 3 fields may be empty if that data is not available.

If there is no :Agent instance for the logged-in user, the URI will revert to their implicitly asserted Role, e.g. for example, :Role_Superuser for an administrator. This is the same URI that appears in provenance metadata entries like dc:creator.

POST Result:
When create=true, the result document is empty, and the status code indicates success:

• 201 when a new User instance was successfully created.
• 409 (conflict) when a User instance already exists - THIS SHOULD BE CONSIDERED SUCCESS!
• Any other code indicates failure.

Access:
Open to authenticated users.

Create New Instance Identifier(s) (/new)

This call creates one or more globally unique, resolvable, URIs for new resource instances. It does not add any data to the repository; the instances will not exist until a user inserts some statements about them. The URI namespace is the default namespace from the configuration properties, followed immediately by the unique identifier. Note that ETL tools may request thousands of URIs at once so the mechanism to produce unique IDs must be able to handle that.

...