ESciDoc Service Interfaces
Disclaimer: Note that the services depicted on this pages are still under development. Some services may be renamed, reassigned to another layer or removed(candidate services). Services marked as <CandidateServices> are still under analysis and will be adressed at a later stage.
eSciDoc services are classified into the following service layers:
On service interfaces[edit]
Core services layer offer two types of interfaces for each resource: SOAP and REST interfaces. More precisely, each resource handler service implements the four basic operations create, retrieve, update, and delete (CRUD) and in addition, filter methods and task-oriented methods (e.g., for changing the status of an object within a content repository) are provided.
- SOAP 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 SOAP interfaces is document/literal.
- REST interfaces are realized through sending a basic HTTP requests (GET, PUT, POST, DELETE) to a resource/subresource URI (each resource has a URI represented via XLink).
Input and output messages for same operations offered by both types of interfaces are specified with the corresponding XML representation. Note: until build 0.94 both SOAP/REST interfaces were based on same schemas. As of build 0.94 this is changed, and the SOAP interfaces use slightly modified schemas(no xlink attributes) then the REST interfaces.
Example 1: create an item
- SOAP: ItemHandler.createItem ("item.xml") (where item.xml is compliant with the SOAP item.xsd schema).
- REST: PUT /ir/item/ (with "item.xml" in the body of the request) (where item.xml is compliant with the REST item.xsd schema)
item.xml (enriched with system generated data is returned if the request is successfully executed)
Example 2: retrieve an item
- SOAP: ItemHandler.retrieve(“escidoc:123”)
- REST: GET /ir/item/escidoc:123
The REST API 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 SOAP API. They use the [JiBX data-binding framework] to transform the XML 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: SOAP 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. SOAP interfaces will be offered for services that are strong reuse candidates for clients outside the core eSciDoc system implementation.