To enable a wide range of integration approaches, we wish to have a flexible HTTP-based API that allows preservation actions to be discovered and invoked. We attempt to follow the RESTful style of invocation as far as possible, but extend it using a simple RPC API where appropriate. Essentially, we wish to declare Preservation Actions as resources that can be discovered and invoked from HTTP, but that invocation itself is fundamentally an remote procedure call, and does not fit easily into a RESTful model.
For example, migration of another resource. This should create a new resource, but we wish to support complex parameters over GET as well as POST, so it is not strictly RESTful.
RPC workflow:
- GET tool/name/action** Returns a resource that describes the action and its parameters.
- GET/POST to tool/name/action/rpc?param=val¶m=val
- Creates and redirects to a new resource describing the successful execution (e.g. /tool/name/action/result/UNIQUE-ID/report)
- Resource containing a reference to the results (e.g. /tool/name/action/result/UNIQUE-ID/output
- GET /tool/name/action/result/UNIQUE-ID/output
- Returns the new resource, e.g. a migrated file.
- Alternative GET/POST the RPC endpoint with a standard flag redirect=true, i.e. GET /tool/name/action/rpc?redirect=true
- Redirects to the new resource directly: /tool/name/action/result/UNIQUE-ID/output
- Alternative GET/POST of the RPC endpoint that acts asynchronously.
- Redirects to a new Job Status result instead, which can be polled.
- When execution is complete, JobStatus object redirects to or becomes a Report resource.
The above is a sketch. It is not RESTful, in for example the GET action can be used to create new resources, by acting as a direct resource proxy. However, it attempts to conform to the http://en.wikipedia.org/wiki/Representational_State_Transfer#Constraints
constraints as far as is possible. In particular, care should be taken to ensure that proxied results are cacheable.
http://en.wikipedia.org/wiki/Remote_procedure_call