Web services

Web Services

(This page is work in progress)

The main interface to the PODD system consists of a set of RESTful web services as described below.

The location of these web services are of the form: http://<host>:<port>/<path_to_podd_service>/<service_name>

For example, services on the prototype may be accessed using: http://poddtest.plantphenomics.org.au/podd/service_name

---

1: PODD RDF web service

Edit PODD artifact service

• Allows editing part of an existing PODD object.
• Previous "Edit object service"
• The user must be authenticated and have proper authorization to access this service.
• Http Method: POST
• URL: http://<server_path>/artifact/edit
• Parameters:
  • artifacturi - The URI of the artifact to edit.
  • versionuri - The version URI of the artifact to edit.
  • objecturi - The URI of the internal PODD object to edit.
  • isreplace - Optional parameter. Default value true. If true, replace any existing statements about these objects, false keeps existing statements.
  • isforce - Optional parameter. Default value false. If true, indicates that any internal objects which lose their links to the top object by the edit should be deleted. If false, when such disconnected objects exist, the edit is aborted and an error returned.
  • The modified RDF statements should be sent in the request body.
• Expected response: Status code 200. Response body contains the updated artifact ID (i.e. ontology IRI, version IRI and inferred IRI) formatted in RDF.
• NOTE: The previous version of the artifact is deleted. This behaviour could be modified to temporarily (for a few hours) keep the previous version internally to aid any UNDO/merge tasks.

Data reference attachment service

• Allows attaching data references to a PODD artifact. A "data reference" refers to a (usually very large) file that is stored in some external repository.
• The user must have authority to edit the given artifact to access this service.
• Http Method: POST
• URL: http://<server_path>/attachref
• Parameters:
  • artifacturi - The URI of the artifact where the data reference needs to be attached
  • versionuri - The Version URI of the artifact where the data reference is to be attached
  • file_verification - "True" or "False" indicates whether the data reference should be verified
  • The content of the POST request must be an RDF fragment specifying the data reference as well as a statement specifying to which object inside the artifact, the data reference should be attached. Some examples of the RDF that may be submitted can be found [here](Data Reference Management).
• Expected response: Status code 200. Response body contains the updated artifact's Inferred OWL Ontology ID.

Ontology resource search service

• This service is for use in the HTML interface.
• Searches for terms matching a given query in the PODD ontologies and a specified PODD artifact.
• The user must have authority to list the artifact in order to access this service.
• Http Method: GET
• URL: http://<server_path>/search
• Parameters:
  • searchterm - The query string for which matching resources are searched
  • artifacturi - Optional parameter. URI of artifact from which search should originate (i.e. decide the contexts to search in)
  • searchtypes - Optional parameter. There can be many of these parameters. Provides URIs indicating the "types" of resources to search in.
• Expected response: Status code 200. Response body containing the matching list of resources. (TODO - alter response format and include here)

Ontology search missing data service

• This service is for use in the HTML interface.
• Accepts a collection of statements with missing information (i.e. missing objects. Missing predicates and subjects are not yet supported) and attempts to fill this missing information from the import closure of the given ontology.
• The user must have authority to list the artifact in order to access this service.
• Http Method: POST
• URL: http://<server_path>/search
• Parameters:
  • artifacturi - Optional parameter. URI of artifact from which search should originate (i.e. decide the contexts to search in). If this is empty, all schema ontologies are used.
  • The content of the POST request must be an RDF fragment listing the required/missing information with special placeholders used to represent missing data. At present, missing rdfs:label values can be identified using the placeholder String Literal "?blank".
• Expected response: Status code 200. Response body contains the statements with missing information filled. Any statements for which the missing information could not be found are omitted from the result.

SPARQL service

• This service is for use in the Client interface generally, although it could also be used in an HTML interface extension.
• Accepts a query and attempts to execute it against the given RDF statements relevant to the given artifacts. For example, the query may just be against the schemas which are relevant to an artifact, and hence may
• The user must have authority to view all of the given artifacts in order to access this service.
• Http Method: POST
• URL: http://<server_path>/sparql
• Parameters:
  • artifacturi - Required, (1 or more) parameter. URIs of artifacts from which SPARQL query should originate (i.e. decide the contexts to search in).
  • query - Required. The SPARQL query to execute
  • includeConcrete - Optional. Whether to include concrete statements for each artifact in the query.
  • includeInferred - Optional. Whether to include inferred statements for each artifact in the query.
  • includeSchema - Optional. Whether to include statements from the imported schema ontologies for each artifact in the query.
• Expected response: Status code 200. Response body contains the statements with the results of the query.

This section last updated: 2013-11-01

2: Prototype RDF web service

Add PODD artifact service

• Load a new artifact (i.e. a PODD object) to the PODD application.
• This service maps to the previous “Object Creation Service”
• The user must be authenticated to access this service.
• Http Method: POST
• URL: http://<server_path>/artifact/new
• Parameters: The artifact content in request body. (Currently supports RDF/XML only.)
• Expected response: Status code 200. Response body contains the URI of the added artifact

Get PODD artifact service

• Download a copy of the specified PODD artifact (i.e. PODD object) as an RDF file.
• Previously Object Details Service
• The user must be authenticated to access this service.
• Http Method: GET
• URL: http://<server_path>/artifact/[base|inferred]/URI
• Parameters:
  • URI - The URI of the artifact to retrieve. The URI should be URL-encoded and the scheme should be followed by a / character instead of the usual ://. (E.g. http/example.org/permanenturl/2c8abf88-3036-4ac5-90d5-5e558d142d64/artifact%3A1)
  • base - Requests the base (asserted) artifact
  • inferred - Requests the inferred statements of the artifact
• Expected response: Status code 200. Response body containing the artifact

Edit PODD artifact service

• Allows editing part of an existing PODD object.
• Previous "Edit object service"
• The user must be authenticated to access this service.
• Http Method: POST
• URL: http://<server_path>/artifact/edit/[merge|replace]/?artifacturi=URI
• Parameters:
  • URI - The URI of the artifact to edit. The URI should be URL-encoded.
  • merge - Merge with existing artifact
  • replace - Replace any existing statements about these objects
  • The modified RDF statements are sent in the request body. (Currently supports RDF/XML only.)
• Expected response: Status code 200. Response body containing the edited artifact URI
• NOTE: The previous version of the artifact is no longer available to users. PODD will however keep it internally temporarily (for a few hours) to aid any UNDO/merge tasks.

Delete PODD artifact service

• An object can be deleted only if it does not have any active children.
• (TODO: Deleting objects within a project is included here)
• Previous "Delete object service"
• The user must be authenticated to access this service.
• Http Method: DELETE
• URL: http://<server_path>/artifact/URI
• Parameters:
  • URI - The URI of the artifact to delete
• Expected response: Status code 200. Response body contains a message with the deleted artifact URI

File reference attachment service

• "This web service makes it possible to attach existing files to a PODD artifact by defining references to it without having to explicitly upload the files. This is especially useful for very large files that would take up too much bandwidth if uploaded to PODD directly. This also leaves the responsibility of file management to the remote data store of the files." - adapted from PODD1.
• The user must be authenticated to access this service.
• Http Method: POST
• URL: http://<server_path>/attachref
• Parameters required to construct a valid file reference vary depending on the type of file reference. For HTTP and SSH file references which are supported at present, the following are expected as query parameters:
  • file_reference_type - either SSH or HTTP
  • artifact_uri - The URI of the artifact where the file reference needs to be attached
  • object_uri - The URI of the object within the artifact to which the file reference is to be attached
  • The content of the POST request must be an RDF document including the details specific to the type of file reference. Some examples of the RDF that may be submitted can be found [here](File Reference Management).
• Expected response: Status code 200. Response body contains the file reference's URI, in plain text or as RDF depending on the HTTP Accept header.

Authentication service

• Authenticates users of the PODD web service
• Login
  • Http Method: POST
  • URL: http://<server_path>/login
  • Parameters: username, password
  • Expected response: Status code 200 (with session information as a cookie)
• Logout
  • Http Method: GET
  • URL: http://<server_path>/logout
  • Parameters: none
  • Expected response: Status code 200

Reset service

• This service is not part of the official PODD service contract. It is an internal service used during development and may not be available in the final version.
• The user must be authenticated to access this service.
• Http Method: GET
• URL: http://<server_path>/reset

3: After the prototype

Add Schema ontology service

• Allows an administrative user to add a new schema ontology or a new version of an existing ontology.
• Only administrative users are authorized to use this service.
• The PODD application should be put to maintenance mode before the service is invoked.

Get Schema ontology service

• Download a copy of the specified schema ontology as an RDF/XML file. Authentication is not required to access this service.
• Maps to the previous “Concept Details Service”.

Enable/disable maintenance mode

• The application needs to be put into a read-only state (for artifacts) before a schema ontology version update and back to its normal state afterwards. Only administrative users are authorized to use this service.

Publish top object service

• A PODD top object (i.e. project) that has a status of "complete" can be published by a suitably authorized user.
• PODD Redesign Specification states: "Once a PODD Artifact is published, a new PODD Artifact must be created internally based on the content and roles assigned to the old PODD Artifact in order to make further changes. The new PODD Artifact may have a link back to the published PODD Artifact, but it will have a new permanent identifier so that it can be distinguished uniquely in future. The basic rationale for this is that the PODD Artifact must be published in the PODD system before it can be cited. Once it is cited, the data that the citation points to must remain constant for a period of time."
• Previous "Publish Project Service"

PODD artifact listing service

• Returns a list of the artifacts (i.e. projects) depending on authorization level of the user.
• Previous Project Listing Service

User management services

• Logout service
• User creation service
• User listing service
• See details [here](User Management)

HTML editing support

File attachment service

• Upload a file through this service to give the responsibility of file storage to PODD.

Get file service

• Download a copy of the specified file (or its meta-data only if requested) from the location where it is stored. This service will internally dereference the file's URI and retrieve it using an appropriate internal service depending on the type of storage.

Project ID service

• Previous Project ID service.

Get project hierarchy service

• Previous Get project hierarchy service.
• Can be part of the Get artifact service. Have an option to include referenced files in the downloaded ZIP file.

Browser Service

• Low priority. Needed for middleware.

Later (depending on time availability)

• Delete file service: Delete the specified file from its remote storage location.
• Search by barcode service
• AAF Authentication service

Services discontinued from the old PODD

• TAB submission service – TAB import will be implemented as a client side utility. PODD itself will not support TAB format.
• Local File attachment service – Was deprecated.