Page History

...

Code Branch

The code of the DSapce 7 REST API have been merged in the master branch: https://github.com/DSpace/DSpace/tree/master/dspace-spring-rest

...

• Add private properties
  • Add a property to the class DSpaceObjectRest
• Add a get/set method
  
• Add get and set to the class DSpaceObjectRest
• To exclude a property from JSON representation, add @JsonIgnore to the get method or to the property
  • Example of exclusion in the class DSpaceObjectRest
  • Another example of exclusion in the class DSpaceObjectRest
• the REST Object should not includes collections (List, Set, etc.) to maintain relations with other REST Objects unless it makes sense to load in memory all the linked objects, instead it should contains information (probably in form of annotation) to discovery linked entities. When a collection could be already available in the corresponding Hibernate object depending on the performed operation the collections should be annotated to provide a more efficient strategy to load the (paginated) information than the native (unpaginated) hibernate lazy-loading

Hateoas Object:  org.dspace.app.rest.model.hateoas.DSpaceResource

...

Provide repository interface functions that return and manage REST representations of DSpace objects. It should provides methods to

• get a specific instance of the object (findOne)
• get all the instances, paginated (findAll)
• save an instance (save)
• delete an instance (delete)
• additional methods should be added following these conventions:
  • find methods: should be annotated so to be discovered as "search" capabilities of the repository and automatically exposed over the /search endpoint sub-path of the resource type(i.e. /items/search/findBySubmitter) - work in progress see 

    Jira
    server DuraSpace JIRA serverId c815ca92-fd23-34c2-8fe3-956808caf8c5 key DS-3544

     for an example
  • massive conditional update/deletion: TBD. Probably it could be useful to introduce an approach similar to the one adopted for find methods with a common /bulk sub-path

Linked Repository Object (TODO - proposal)

Resources are typically linked with other resources of the same of different type. For example a collection is linked with the items that belong to the collection. It is not effective to include a list of items in the collection object because it doesn't scale. Also if the Hateoas object can wrap the list adding pagination on the server side we will have hit the full list. This mean that the linked objects need to be retrieved using optimized and paginated methods. This could be done essentially in two ways:

1. the Hateoas object adds a link, say items in the CollectionResource that refers to a search methods in the item repository (i.e. /items/search/findByCollection). The limit of this approach is that update of association couldn't be addressed on the same endpoint breking one of the REST principle related to the URL structures and HTTP verbs. It doesn't make sense to send a POST to the endpoint  /items/search/findByCollection?id=xxxx to map a new item under the collection xxx. The same issue arise if we work on the other side of the relation, i.e. if we put the focus on the single item we will end with the endpoint /collections/search/findByItem?id=xxx.
   This mean that the search endpoint should be used for read-only relations or "custom views" over a relation.
2. the link is managed directly at the resource level. In our example this mean that the items link will refers to an endpoint like /collections/:uuid/items 
   This bring the issue to decide where put the implementation of the retrieval logic. It could be placed in the Repository Object assigned to the specific type (for example CollectionRestRepository) or in a separate class. According to the Repository Pattern (https://martinfowler.com/eaaCatalog/repository.html) a repository is dedicated to a single Business Entity so this should be avoid. Thinking to the relation in terms of a separate Business Entity, it makes sense to define a specific repository for this Entity, the Linked Repository Object. This is the approach that we are currently exploring to solve 

   Jira
   server DuraSpace JIRA serverId c815ca92-fd23-34c2-8fe3-956808caf8c5 key DS-3489

   Jira
   server DuraSpace JIRA serverId c815ca92-fd23-34c2-8fe3-956808caf8c5 key DS-3483

   Jira
   server DuraSpace JIRA serverId c815ca92-fd23-34c2-8fe3-956808caf8c5 key DS-3485

   Jira
   server DuraSpace JIRA serverId c815ca92-fd23-34c2-8fe3-956808caf8c5 key DS-3533

   
   
   

In

Managing Object Initialization (TODO)

• When referencing a linked object, how do we control the initialization/load of reference object?
  Proposal: as manage partial object is a common scenario in REST implementation regardless to the representation format used (HAL in our case). It makes sense to add support for this capability directly on the RestModel base class. It should be able to discriminate which properties are really null and which are uninitialized allowing the HAL Wrapper to lazy load relation if needed (see Linked Repository Object). The Converter object should set only properties that are already initialized in the Hibernate object avoiding to hit hibernate lazy loading. If the property is required to be included in the requested projection Hibernate Lazy load should be used only if there are not a defined Linked Repository Object able to manage the requested relation

Build the REST Controller(s)

The goal is to have a pluggable infrastructure so that new endpoint can be added implementing the previous relevant classes without the explicitly need to add new Spring MVC controllers. This assure easy and maintenable uniform implementation of the behavior described in the REST contract in terms of HTTP Verbs meaning, ETAG, URL structure, etc.

Up to now we have two REST controller

• org.dspace.app.rest.RootRestResourceController 
  It is responsible to produce the root HAL document listing all the defined endpoints of the REST API
• ALPSController (TODO). 
  It will be probably introduced to add support for the ALPS protocol, see 

  Jira
  server DuraSpace JIRA serverId c815ca92-fd23-34c2-8fe3-956808caf8c5 key DS-3486

  
  
  
• org.dspace.app.rest.RestResourceController
  It is the single point of entry of all the REST requests related to resources. It delegates the retrieval and save logic to the Repositories, HAL wrappers and Converters previously described.

For specific functionalities it will be probably easier to create a separate controller instead to force the use of the Repository model. This is true for features that don't deal with a specific resource like the ROOT HAL Document, ALPS, the global search (Discovery)