ESciDoc Service Interfaces
Core services layer offer two types of interfaces for each resource: SOAPSimple Object Access Protocol and RESTRepresentational State Transfer interfaces. More precisely, each resource handler service implements the four basic operations create, retrieve, update, and delete (CRUDCreate, Retrieve, Update and Delete) and in addition, filter methods and task-oriented methods (e.g., for changing the status of an object within a content repository) are provided.
- SOAPSimple Object Access Protocol interfaces are realized through resource handlers that offer operations for a specific service functionality that is to be applied to the resource itself or a distinctive part of the resource (subresource). The messaging style for SOAPSimple Object Access Protocol interfaces is document/literal.
- RESTRepresentational State Transfer interfaces are realized through sending a basic HTTPHyperText Transfer Protocol requests (GET, PUT, POST, DELETE) to a resource/subresource URIUniform Resource Identifier (each resource has a URIUniform Resource Identifier represented via XLink).
Input and output messages for same operations offered by both types of interfaces are specified with the corresponding XMLExtensible Markup Language representation.
Note: until build 0.94 both SOAPSimple Object Access Protocol/RESTRepresentational State Transfer interfaces were based on same schemas. As of build 0.94 this is changed, and the SOAPSimple Object Access Protocol interfaces use slightly modified schemas then the RESTRepresentational State Transfer interfaces.
Example 1: create an item
- SOAPSimple Object Access Protocol: ItemHandler.create("item.xml") (where item.xml is compliant with the SOAPSimple Object Access Protocol item.xsd schema).
- RESTRepresentational State Transfer: PUT /ir/item/ (with "item.xml" in the body of the request) (where item.xml is compliant with the RESTRepresentational State Transfer item.xsd schema)
item.xml (enriched with system generated data is returned if the request is successfully executed)
Example 2: retrieve an item
- SOAPSimple Object Access Protocol: ItemHandler.retrieve(“escidoc:123”)
- RESTRepresentational State Transfer: GET /ir/item/escidoc:123
The RESTRepresentational State Transfer APIApplication Programming Interface differentiates between resource- and task-oriented methods. All resource-oriented methods use GET, PUT and DELETE verbs. Task-oriented methods use the POST verb.
At present, intermediate and application services implemented in Java invoke the core services via the SOAPSimple Object Access Protocol APIApplication Programming Interface. They use the [JiBX data-binding framework] to transform the XMLExtensible Markup Language representation of resources returned by Basic services, since it allows for the definition of custom mappings to Java classes.
Services on intermediate and application layers offer two types of interfaces: SOAPSimple Object Access Protocol and standard Java interfaces. Standard Java interfaces will be offered for internal communication between service components of the application and intermediate layer – in this case input and output are standard input/output Java types. SOAPSimple Object Access Protocol interfaces will be offered for services that are strong reuse candidates for clients outside the core eSciDocEnhanced Scientific Documentation system implementation.
Interface specification can be found at eSciDoc project pages