...

1. It has a unique subject URI, and exactly one asserted rdf:type statement.
2. Its rdf:type (possibly an inferred type) is a member of the designated class group indicating embedded instances. In the eagle-i data model the URI of this class group is:

   Code Block
   http://eagle-i.org/ont/app/1.0/ClassGroup_embedded_class

3. It has exactly one parent. There is exactly one instance, which is the subject of statements for which the EI is the object. This is an informal restriction (really an assumption) imposed on all instances of embedded types, although it is enforced by logic in the repository.
4. EIs may not be Orphaned or Shared. Any transaction that would result in an EI left without a parent, in other words it is **{}not{}* the object of any conforming statements, *{}or* it has multiple parents, is forbidden by logic in the repository. The only way to remove an EI from its parent is to delete all of its statements. You can copy an EI to another parent by creating a new EI under that parent, with a new unique URI for its subject.
5. No Broken Links to EIs. If an EI is removed, an instance cannot retain any statements of which it is the object. These must be removed.
6. EIs do not Have Metadata. The repository does not create metadata, Dublin Core, for example, about EIs. Any transactions on the EI are considered transactions on its parent and recorded as such, in the last-modified date in the metadata.
7. Transactional Integrity All transactional operations, such as /update and workflow, operate on the EI statements together with the parent instance's statements. For example, a workflow transition to published moves all the EIs to the published graph along with their parent's statements.
8. EIs reside in the same graph as the parent. Though it seems obvious, it's worth stating formally that the statements describing an EI must reside in the same named graph (workspace) as the statements of its parent.

...

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.

...

Access:
Requires a login and established session.

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.

...

*Access:
Requires a login and established session.

Check or Load Data Model Ontology (/model) - Admin Only

This service either reports on or loads the Data Model Ontology. The GET request returns a report of the version of the ontology loaded, and the version that is available to be automatically loaded from within the repository's codebase. The POST request give a choice of selective update or forcibly replacing the ontology.

...

The source argument determines where the ontology data comes from. When source=jar, which is recommended, the ontology is the collection of all OWL files in the maven package eagle-i-model-owl}}as it was loaded into the repository's source base. This ought to reflect the version of the ontology for which the sofware was designed. When {{source=model, the EIOntModel is used as the data source. Although there should be no difference between them, because the EIOntModel is loaded in to Jena from the same source files, in practice there appears to be some differences.

Manage Internal Graphs (/internal)

URL: /repository{}/internal (GET, POST)

...

This is a multi-function service, depending on the value of action: When action=load, replaces contents of an internal graph with hte initializer in the webapp. For action=read, returns contents of initializer for given graph in the result docuemnt. For action=query, runs given SPARQL query over contents of initializer(s) for given graphs (this is the ONLY form that can take multiple graphs). For action=decache, tells repository server to decache all in-memory data derived from RDF content in case, for example, the internal graphs have been modified or updated. All of these actions require Administrator privilege.

Harvest Resource Metadata (/harvest)

This service harvests the "metadata", which is actually the resource instance data from the repository. It is intended to be used by an external search index application to keep its index up-to-date by incremental updates, since that is much more efficient than periodically rebuilding the index.

...

Access control:
Read permission is required on all desired graphs.

Export and Import of Users, Resource Instances (/export, /import)

This service lets you export the users OR data contents of one repository and import them into a different one, or a later instance of the "same" repository. It is intended to migrate and mirror data between different releases of the software and ontology, or different deployments created for testing. Although the same service can handle both "user" and "resource" instances, these are two separate operations and cannot be combined.

...

• If the URI prefix is different in the destination, do you transform the subject URIs so they are resolvable, or keep the original URIs to match the source?
• How do you want to handle a duplicate instance in the import (i.e. when the same instance already exists in the repository)?
• Should a resource instance import be allowed to create new named graphs?

URL: /export (GET or POST method)

Args:
format---MIME type of the serialization format to be output. By default, it is chosen by HTTP content negotiation. Must be capable of encoding quads; default is TRiG (application/x-trig).
type=(user|resource|transition|role|grant)---which type of data is to be exported, one MUST be chosen and there is no default.
view---(only when type=resource) optionally choose a different view dataset from which to select the graph(s) for export. Mutually exclusive with workspace. Default is the published-resources view. Be careful to choose a view that does not include repository user instances.
workspace---URI of the workspace named graph to take the place of the default graph. Relevant metadata and ontology graphs are included automatically. Mutually exclusive with view.
include=list..---Explicit list of user or resource instances to include in the export.Format is a series of resource URIs separated by commas (",") and optional spaces. Users may also be referenced by username.
exclude=list..---Explicit list of user or resource instances to exclude from the export. Mutually exclusive with include, format is the same as the include list.

Result of an export request is a document of serialized RDF data in the requested format, unless the HTTP status indicates an error. Note that inferred statements are never included. This document is ONLY meaningful to an /import request by the same or another data repository. It is not intended to be human readable or meaningful. Its contents may not necessarily reflect the source repository's content directly.

Access control: Only the superuser may export users. Read access on the resident named graphs is required to export resource instances.

About Export/Import of Access Grants: For most types, the export includes access grants since these are considered administrative metadata. The type of "grant" is included so you can export and import just the grants on any URI, mainly to give you a way to transfer the access grants on Named Graphs (Workspaces). Also see the ignoreACL option on /import.

About Format and Charset of Imported Document: By default, format is indicated by the content arg's Content-Type header, at least when it is a separate entity in a POST entity body of type multipart/form-data. However, this is not always easy to control in an HTTP client. You can override it with the format arg. If a charset parameter is not specified in the content-type value, it defaults to UTF-8. Also note that the format must be capable of encoding quads; e.g. TRiG (application/x-trig).

URL: /import (POST method only)

Args:
format---the MIME type (and charset) of the input document's serialization format. This overrides any content-type on the content arg's entity.
type=(user|resource|transition|role|grant)---which type of data is to be imported, one MUST be chosen and there is no default. MUST match the type of the exported data.
content=stream..---the serialized RDF data to import, must have been generated by export of the same type of data.
transform=(yes|no)---Required, no default. When 'yes', URIs of imported instances are transformed into new, unique URIs resolvable by the importing repository. When 'no', URIs are left as they are.
duplicate=(abort|ignore|replace)---how to handle an import that would result in a duplicate object. Default is abort.
newgraph=(abort|create)---how to handle a resource instance import that would result in creating a new named graph for the data. Must be superuser to choose 'create'. Default is abort.
{{include=list.. }}---Explicit list of user or resource instances to include in the import. Format is a series of resource URIs separated by commas (",") and optional spaces. Users may also be referenced by username. IMPORTANT NOTE: The URIs in the include (and exclude) lists are matched against URIs in the imported source file, NOT the repository.
{{exclude=list.. }}---Explicit list of user or resource instances to exclude from the import. Mutually exclusive with include, format is the same. Useful for avoiding conflicts e.g. , for example, when loading a user export into a repository where the initial admin user already exists.
ignoreACL=(true|false)---Ignore all access control grants on imported objects. The imported objects will not have any specific access grants.

Send Contact Email - /emailContact

This service was originally updated as a very rushed proof-of-concept and has not been rigorously designed, so it does not have a specification of behavior. This section only documents how to call it, the internal actions it takes are still under discussion.

URL: /emailContact (POST method only)
Args:
uri=subject-URI---required
client_ip=IP addr---required
from_name=personal name---required
from_email=mailbox---required
{{subject=text
{{message=text
test_mode---default false, true if present.

Sends an email message to teh the designated contact contacts for the resource identified by uriURI. The exact rules for determining that contact address have not been formally specified yet. When a contact cannot be determiend, the mail is sent to the configured postmaster for hte repo. See the Admin Guide for details about configuring that and the rest of the email service.

Workflow Services REST API

Show Transitions

/repository/workflow/transitions
Method: GET or POST
Args:
workspace=URI---restirct results to transitions applying to given workspace (includes wildcards). Default is to list all.
format=mime- tyep --type of result.

Returns the selected workflow transitions as SPARQL tabular results.
Result columns are:

• Subject URI
• Label
• Description
• Workspace URI
• Workspace Label
• initial-state URI
• initial-state Label
• final-state URI
• final-state Label
• allowed - boolean literal, true if current user has permission on this transition

Show Resources

/repository/workflow/resources
Method: GET, POST
Args:
state=URI|all---workflow state by which to filter, or 'all' for wildcard.
type=URI - include only instances of this tyep (by inference counts) - default is no restriction.
unclaimed=(true|false)---when true, unclaimed resources are included in the report. Default is true.
owner=(self|all|none)---show, in addition to any selected unclaimed resources:

• self - those claimed by current user
• all - instances claimed by anyone
• none - includes no claimed resources.
  Default is self. Note that the combination unclaimed=false and owner=none is illegal.
  workspace=URI---restirct results to resources in a given workspace; optional, default is all avaialble worksaces.
  format=mime---

...

• type of result, one of hte SPARQL query formats.
  detail=(brief|full)---columns to include in results, see description below.
  addPattern=SPARQL-text---add this triple pattern to SPARQL query. May refer to variables as described below. Value is a literal hunk of triple pattern ready to be inserted into the patterns of a SELECT query. It may refer to the result variables mentioned below, e.g. ?r_type.
  addResults=query-variable..---add these variables to results columns. value is expected to be a space-separated series of query variables (which must appear in the triple pattern), e.g. "?lab ?labname"
  addModifiers=modifiers..---add a SPARQL modifiers clause to the query. Modifers include ORDER BY, LIMIT, and OFFSET and can be used to implement pagination.

This request returns descriptions of a selected set of resources in SPARQL tabular result form. It is intended to be used to populate menus and autocomplete vocabularies, as well as more complex table views.

• The brief level of detail includes columns:
  • r_subject - URI of resource instance
  • r_label - label of resource instance
  • r_type - URI of instance's asserted type
• The full level of detail adds the fields:
  • r_created - created date from provenance
  • r_owner - URI of workflow claimant if any
  • r_ownerLabel - the rdfs:label of r_owner if it is bound (and has a label)
  • r_state - URI of workflow state
• Any query variables you specified in the addResults list are added to either result.

Claim Resource Instance

/repository/workflow/claim
Method: POST
Args:
uri=URI---subject to claim
user=UserURI---optional, user who asserts the claim; default is authenticated user.

Asserts a claim on the given instance. This requires the following:

• user must have access to a transition out of the current state.
• user must have read access to instance
• there is no existing claim on the instance.

There is no result document. The status indicates success with 200. As side-effects, this actino also:

1. Adds insert and delete access to the instance for the claiming user.
2. Sets :hasWorkflowOwner property to the claimant (in an internal metadata graph)

Release (claimed) Resource Instance

/repository/workflow/release
Method: POST
Args:
uri=URI---subject to release

Requires that current user is the owner, or Administrator role.. As side

Side effects:

Removes insert and delete access to the instance for the current user.
Removes :hasWorkflowOwner property (in an internal metadata graph)

Transition on Resource Instance

/repository/workflow/push
Method: POST
Args:
uri=URI---subject to transition
transition=URI---indicates transition to take

Requires:

1. read access to instance.
2. must be claimed
3. user should be either claim owner or Administrator
4. user must have READ access on the chosen Transition.

Side-effects include:

• Implied release of any current claim (and all applicable side-effects of that)
• Executes action associated with this transaction, if any.
• Resource's workflow state will become the final state of the transition.

Admin UI Support Services

There are also some REST services created to support the administrative GUI (the JSP pages). They are NOT intended to be part of the regular API since their exact function and parameter structure is dictated by the JSPs and is thus still somewhat fluid. Most of them also require Administrator access.

If you use these services, it is at your own risk, and thus they are not documented. See the JSPs for usage examples if you are really curious. The URLs are as follows:

/repository/admin/updateUser
/repository/admin/updateGrants
/repository/admin/updateRole
/repository/admin/updateTransition
/repository/admin/updateNamedGraph

Site Home Page

Since the repository webapp is installed as the ROOT webapp (so it can have control over the URL space for the purpose of resolving all of its resource instances), it also controls the site's top-level "home" (index) page. The site home page is not part of the API, however, so it does not need to control the content of that page.

In order to give the site administrator control over the content of the site home page, the repo lets you redirect it to any URL, under the control of a configuration property. See eaglei.repository.index.url in the configuration properties.

Services to Support Admin GUI Pages

These REST services were included to support the administrative GUI, which is implemented as JSPs. They are targeted precisely at serving as the back end of the JSPs, so their range of function is strictly limited and they are effectively "write-only". Typically you call on the service and the HTTP status says whether it succeeded or failed; it does not return a detailed report.

...

Access Control: All services except updateUser require superuser privilege. Since a user may update his/herself (except for roles) that is also allowed by the back-end service.

The services are as follows – red follow. Red marks required args.

Update User Account

/repository/admin/updateUser

Method: POST
Args:
username=text---account name to change, only not required for create
only_password=(boolean)---do not process changes to user metadata, just update password
password---new password
password_confirm---must match new password
old_password---current (old) password, required for non-admin user
first---first name of person (metadata)
last---last name of person (metadata)
mailbox---email address of person
role---URI of role to add to user - , may be multiple; when specified, this list of roles replaces the user's current roles.

If current user is not an Administrator, there are these restrictions:

• Cannot create new users
• Can only change your own user account
• Must supply old password to change password
• Cannot change roles

Update Role

/repository/admin/updateRole

Method: POST
Args:
action= create | update | delete---(keyword)
uri=URI---required except for create, identifies the role
label= text---immediate label of role
comment= text---lenghty description of the role

Update Grants

/repository/admin/updateGrants

Method: POST
Args:
{{action{*}= {{add | remove }}---(keyword)
uri = URI---subject of the access grant
access= {{URI }}---access type to be added or removed
agent = URI of person or Role in the grant

Update Workflow Transition

/repository/admin/updateTransition

Method: POST
Args:
action= create | update | delete}}---(keyword)
uri = URI--required except for create, identifies the role  uri=URI--subject to release
{{label =text}}---required to create
comment =text (description)
{{ initial}}= URI of initial state (required to create)
final=URI of final state (required to create)
tAction=java class of transition action provider
tActionParameter* = text or URI param to pass to action method
order= sorting key, usually a decimal integer

Update Named Graph

/repository/admin/updateNamedGraph

Method: POST
Args:
uri*=URI names the graph or context
label=text
type=URI of a NamedGraph Type

Interactive Web UI Pages

Although the repository is mostly accessed by other programs through  the HTTP REST API, there are a few pages available to interactive users.

HTML Dissemination View of a Resource Instance

The dissemination servlet that makes resource instances resolvable also generates an HTML page for interactive users when content negotiation selects the text/html format.  The HTML renders properties and the values of object properties as links to their URIs, so they can be resolved easily. 

The page should also include an accurate Last-Modified date header, and respond appropriately to the If-Modified-Since HTTP header, which is used by Web proxies and search engine crawlers to update their caches.

See the eaglei.repository.instance.xslt configuration property for instructions on adding an XSLT transformation stage into the pipeline that delivers HTML content. (Sorry, we haven't washed away all of the Cocoon kool-aid yet..)

Administrative UI pages (/admin)

Visit this page for a directory of all administrative UI functions.  Users without superuser privilege will only see a partial list.  It also displays server-status and configuration details.

 http://_hostname_/repository/admin 

Although almost all repository administration is done by manipulating RDF statements in an internal administrative-metadata graph, there is a need for a Web-based UI to make it easier for site administrators to see and change the current state. Except as noted, these pages are only available to users with the Administrator role:

• Interactive SPARQL query workbench (all auththenticated users).
• List Named Graphs with the option to edit their descriptive metadata and ACLs.
  • Note that new Named Graphs are only added with the /graph service.
• List, add, delete, and modify access Roles - edit the metadata of each Role.
• List, add, and modify User login accounts:
  • Display and change membership in roles.
  • Edit user metadata and change password.
  • Disable a user from logging in at all, or reinstate disabled user.
• List, add, delete, and modify Workflow Transitions.
• Report versions of Data Model Ontology: loaded, and available.
• Get a list of Published Resources. This is handy for troubleshooting (all users).

Search Engine Control

• {{/robots.txt}---direct robots to a site map, warn them away from other pages.
• site maps---HTML and XML site maps to direct crawlers to pages we want them to index.