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.

README

Please include a README with a ResourceRS that includes:

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

Creating a new ResourceRS

New ResourceRSs should be included as a separate module under the pic-sure-resources module. ResourceRSs should have a unique @Path for PICSURE-2.0 to direct resource calls to.

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.

Throwing Errors

When throwing an error, if possible, please use one of PICSURE-2.0's errors located in the pic-sure-util module. This will ensure that the error message is correctly passed to the user. Common error messages are included as static Strings in the relevant Exception class.

• ApplicationException should be thrown whenever the error is with the code or configuration. Some possible cases include:
  • MISSING_TARGET_URL : The targetURL should have been added to the request by the service layer
  • MISSING_RESOURCE_PATH : The resourceRS path should also have been added by the service layer
  • MISSING_RESOURCE : A query stored in the database should have its corresponding resource included
• NotAuthorizedException should be thrown whenever there is a problem with credentials, i.e. the resource throws a 401.
  • MISSING_CREDENTIALS : use when the credentials have not been included (or perhaps have been mislabeled in the resourceCredentials map)
• ProtocolException should be thrown when there is a problem with the request submitted.
  • MISSING_RESOURCE_ID : Requests should have a value in the resourceUUID field
  • RESOURCE_NOT_FOUND : The submitted resourceUUID does not match any installed resource
  • MISSING_DATA : Some part or all of the data required for this request is missing
  • MISSING_QUERY_ID : The query id for a query/status or query/result request is missing
  • QUERY_NOT_FOUND : The submitted query id does not match any in the database
  • INCORRECTLY_FORMATTED_REQUEST : The query request submitted is not in the expected format
• ResourceInterfaceException should be thrown when there is a problem with the resource

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

Utility methods

There are various utility methods in HttpClientUtil