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.

...

This service actually implements three different kinds of requestrequests:

1. Create a new resource instance (,including embedded instances) - . It must specify its home graph.
2. Obtain the edit token with which to modify an existing resource instance.
3. Modify ("update") the properties of a resource instance, both delete and add in one transaction. This includes adding, deleting, and modifying any embedded instances.

Update The update operation does all its work in the instance's home named graph. For an existing instance being modified, it is computed as the named graph in which the asserted rdf:type statement(s) are found.

When creating new resources: Since the create operation hasndoesn't got have an instance from which to derive its home graph, its home graph must be specified as the workspace arg.

Workflow Implications of Creating New Resourcesimplications of creating new resources: Since the /update action that creates a new resource instance is effectively performing a transition from the New workflow state, the current user must have permission to make such a transition to the destination workspace; if there are multiple transitions, one is chosen arbitrarily.

On the Acquiring and Use use of Edit Tokensedit tokens: The edit token is intended to "protect" the read-only copy of the instance that you (presumably) download as a basis for edits. The correct sequence of operations when modifying an instance is:

1. Obtain the edit token.
2. Get RDF for the resource instance.
3. Submit an /update request to modify the resource instance, with token (1).

This ensures that no matter how much time passes between (2) and (3),   if, for example, a user dawdles over an interactive edit or forgets and leaves it overnight, the edit token is already in place to indicate his/her intention to make a change. It does not prevent another user from coming along and grabbing the token to make a change, but it will indicate that there is an edit in progress, and it will prevent a stale copy from being checked in.

Comparison Comparison with SPARQL/UPDATE: In case you are wondering why we chose to implement this complex special-purpose service instead of a general protocol like SPARQL/UPDATE - there were some compelling reasons:

1. Too difficult to impose the necessary fine-grained access controls on SPARQL/UPDATE. This service is defined to be a transaction that only affects one resource instance (and its embedded instances).
2. Major benefit of S/U protocol is accepting a list of deletes and a list of inserts, which we do here.
3. SPARQL/UPDATE is still not a recognized standard, and implementations are poor.

When action=create, there must be no existing statements in the repo repository with the given URI as a subject. The request must include an insert arg containing one or more statements whose predicate is rdf:type. (All of the subjects must match the request URI). It is an error to specify a delete arg.

When action=gettoken, an edit token is created if necessary, and returned along with the user who created it, time it was created, and a boolean value that is true if it was newly created by this request. This information is intended to help a UI service advise the user when there might be an edit in progress, i.e. if the boolean was false and the timestamp on the token is recent.

When action=update, there must be an existing instance matching the URI of the request. DO NOT specify the workspace arg, since the repository automatically finds the instance's home graph and makes all changes there.

Updating a resource instance's properties requires an edit token. The token lets the server check that your edits are based on the current valid state of the resource; if another update occurs before yours, its changes could be corrupted or lost. To update, first, run the /repository/update request with the arg, action=gettoken to obtain the current edit token, creating one if necessary. Then, get the content properties as before. When calling /repository/update again with action=update add the token=token-uri arg.

Note on File Format and Character Setfile format and character set: The request specifies the file format and/or character set of the serialized RDF data as a Content-Type header value in the entity bodies of insert and delete args, e.g. , for example, 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. The content-type can be provided in two different places – they are searched in this order of priority, and hte the first one found is the only one considered:

• Content-Type---header on the value of the content entity in a POST request. This takes precedence because it allows for different content-types in insert and delete args.
• format---query argument value.

*URL:* {{/repository/update \[ /instance-ID  \]}} (POST only)

Args:
{{uri---}}optional way to explicitly specify the complete URI, instead of assuming that the URI's namespace matches the hostname, context, and servlet path ("/i") of this webserver.
format---the default expected format for insert and delete graphs. If the args specify a content-type header, that overrides this value. Only recognizes triples even if the format supports quads.
action=(update|create|gettoken)---Update to modify an existing instance, create adds a new one. See below for details about gettoken.
token=uri---When action is update or create, this must be supplied. The value is the URI returned by the last gettoken request.
workspace=uri---Choose workspace named graph where new instance is created. Only necessary when action=create. Optional, default is the default workspace. DO NOT specify a workspace when action=update.
delete---graph of statements to remove from the instance; subject must be the instance URI. Deletes are done before inserts. Graph may include wildcard URIs in predicate and/or object to match all values in that part of a statement.
insert---graph of statements to add to instance; subject must be the instance URI.
bypassSanity---(boolean, default false, deprecated) - NOTE: It is best if you pretend this option does not exist. When true, it skips some of the sanity tests on the resulting instance graph, mostly the ones checking the integrity of Embedded instances. Requires Administrator privilege. This was added to make the data migration from broken old EI data possible, it should rarely if ever be needed now.

The delete wildcard URI is http://eagle-i.org/ont/repo/1.0/MatchAnything

...

When action=gettoken, the response includes a document formatted (according to the chosen format) as a SPARQL tuple result. It includes the columns:

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 gettoken operation created a new token. when false, taht means the token already existed, which indicates there MAY already be another user's update in progress which might conflict with yours. (see the created and creator values)
creatorLabel---rdfs:label--of the creator if available.

...