Implementing a ResourceRS

Each type of resource needs its own ResourceRS. These must implement IResourceRS.

All requests are POSTs that take in a QueryRequest object.

If your resource has no equivalent for a particular method, please throw an UnsupportedOperationException.

README

Please include a README with a ResourceRS that includes:

• Keys in the resourceCredentials map
• path to the ResourceRS
• example queries

Calling Your Resource

Each QueryRequest has a targetURL that should point to an instance of your resource. This will have been configured on the PICSURE-2.0. Use this as the baseURL and add the necessary path following it to reach a particular endpoint.

Using Resource Credentials

Each QueryRequest has a resourceCredentials map that should contain any credentials required to access the resource. The keys in this map that your ResourceRS will be looking for should be identified in a README so that system admins can give instructions when installing that resource on a PICSURE-2.0 instance.

Endpoints

/info

If your resource has no info endpoint, you may construct an info response. (See HSAPIResourceRS for an example). The ResourceInfo object contains a name (of the resource), an ID, and a list of QueryFormats. QueryFormat has a name, description, specification, and examples, so the info from your resource or that you construct must fit this format. The QueryFormatDeserializer will label anything that is not name, description, or examples as specification. Specification is a map and can contain any relevant information specifying the resource. Examples is an array of maps. Each map should be an example query to send.

/search

The SearchResults object that this endpoint returns can return results in any form - the results field is simply an Object. Additionally, there is a String field searchQuery where the original query submitted should be stored.

Queries

All queries are stored in the PICSURE-2.0 database with the original query request. The UUID of these queries can be used to request query status, result, or metadata, and contains the resource result ID as well as the status (as of the last time it was checked).

/query

This endpoint is for asynchronous queries. It returns a QueryStatus with a resource result id so that the result can be fetched later through the /query/{queryId}/result endpoint. In addition to the resourceResultId, the resource status should be mapped to a PicsureStatus. The resultMetadata field can be used for any additional data that needs to be saved with this query.

/query/{resourceQueryId}/status

The resourceQueryId should match the id of a saved query on your resource. This endpoint returns the same object (QueryStatus) as the /query endpoint.

/query/{resourceQueryId}/result

This endpoint returns the response from the resource as-is.

/query/sync

This endpoint is for synchronous queries which immediately return a result. It returns the response as-is.