Package org.trustdeck.controller

Class EntityInstanceRESTController

java.lang.Object
org.trustdeck.controller.EntityInstanceRESTController
@RestController @EnableMethodSecurity @RequestMapping("/api") public class EntityInstanceRESTController extends Object
This class offers a REST API for interacting with entity instances.
Author:
Armin Müller

  • Constructor Summary

    Constructors
    Constructor
    Description
    EntityInstanceRESTController()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    org.springframework.http.ResponseEntity<?>
    createEntityInstance(String projectAbbreviation, String entityTypeName, EntityInstanceDTO entityInstanceDTO, String responseContentType, jakarta.servlet.http.HttpServletRequest request)
    Endpoint to create a new instance of an entity type.
    org.springframework.http.ResponseEntity<?>
    deleteEntityInstance(String projectAbbreviation, String entityTypeName, String trustDeckId, String responseContentType, jakarta.servlet.http.HttpServletRequest request)
    Endpoint to delete an entity instance.
    org.springframework.http.ResponseEntity<?>
    getEntityInstance(String projectAbbreviation, String entityTypeName, String trustDeckId, String responseContentType, jakarta.servlet.http.HttpServletRequest request)
    Endpoint to retrieve an entity instance.
    org.springframework.http.ResponseEntity<?>
    recordLinkage(String projectAbbreviation, String entityTypeName, EntityInstanceDTO entityInstanceDTO, String responseContentType, jakarta.servlet.http.HttpServletRequest request)
    Endpoint to check if there are entities in the database similar/equal to the given one.
    org.springframework.http.ResponseEntity<?>
    searchEntityInstance(String projectAbbreviation, String entityTypeName, String query, String responseContentType, jakarta.servlet.http.HttpServletRequest request)
    Endpoint to search for entity instances.
    org.springframework.http.ResponseEntity<?>
    updateEntityInstance(String projectAbbreviation, String entityTypeName, String trustDeckId, EntityInstanceDTO entityInstanceDTO, String responseContentType, jakarta.servlet.http.HttpServletRequest request)
    Endpoint to update an entity instance object.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • EntityInstanceRESTController

      public EntityInstanceRESTController()

  • Method Details

    • createEntityInstance

      @PostMapping("/projects/{projectAbbreviation}/entities/{entityTypeName}") @PreAuthorize("hasRole(\'project-entity-instance-create\')") public org.springframework.http.ResponseEntity<?> createEntityInstance(@PathVariable("projectAbbreviation") String projectAbbreviation, @PathVariable("entityTypeName") String entityTypeName, @RequestBody EntityInstanceDTO entityInstanceDTO, @RequestHeader(name="accept",required=false) String responseContentType, jakarta.servlet.http.HttpServletRequest request)
      Endpoint to create a new instance of an entity type. If a domain is associated with the given type, this endpoint automatically creates a pseudonym in the associated domain.
      Parameters:
      projectAbbreviation - the abbreviation of the project to which the request is scoped to
      entityTypeName - the name of the entity type associated with this instance
      entityInstanceDTO - the data transfer object containing this instance's data
      responseContentType - (optional) the response content type
      request - the request object, injected by Spring Boot
      Returns:
    • a 201-CREATED status with the created entity instance on success
    • a 400-BAD_REQUEST status when the instance payload is missing/invalid or fails schema validation
    • a 404-NOT_FOUND status when the project or entity type does not cannot be found
    • a 410-GONE status when the project has ended or the entity type is marked as deprecated
    • a 422-UNPROCESSABLE_ENTITY status when creation failed

    • getEntityInstance

      @GetMapping("/projects/{projectAbbreviation}/entities/{entityTypeName}/{trustDeckId}") @PreAuthorize("hasRole(\'project-entity-instance-read\')") public org.springframework.http.ResponseEntity<?> getEntityInstance(@PathVariable("projectAbbreviation") String projectAbbreviation, @PathVariable("entityTypeName") String entityTypeName, @PathVariable("trustDeckId") String trustDeckId, @RequestHeader(name="accept",required=false) String responseContentType, jakarta.servlet.http.HttpServletRequest request)
      Endpoint to retrieve an entity instance.
      Parameters:
      projectAbbreviation - the abbreviation of the project to which the request is scoped to
      entityTypeName - the name of the entity type associated with this instance
      trustDeckId - the unique UUID for this entity instance
      responseContentType - (optional) the response content type
      request - the request object, injected by Spring Boot
      Returns:
    • a 200-OK status with the requested entity instance on success
    • a 404-NOT_FOUND status when the project, entity type, or instance cannot be found
    • a 410-GONE status when the project has ended or the entity type is marked as deprecated

    • updateEntityInstance

      @PutMapping("/projects/{projectAbbreviation}/entities/{entityTypeName}/{trustDeckId}") @PreAuthorize("hasRole(\'project-entity-instance-update\')") public org.springframework.http.ResponseEntity<?> updateEntityInstance(@PathVariable("projectAbbreviation") String projectAbbreviation, @PathVariable("entityTypeName") String entityTypeName, @PathVariable("trustDeckId") String trustDeckId, @RequestBody EntityInstanceDTO entityInstanceDTO, @RequestHeader(name="accept",required=false) String responseContentType, jakarta.servlet.http.HttpServletRequest request)
      Endpoint to update an entity instance object. Updatable attributes are data, is_deleted, created_at, and updated_at.
      Parameters:
      projectAbbreviation - the abbreviation of the project to which the request is scoped to
      entityTypeName - the name of the entity type associated with this instance
      trustDeckId - the unique UUID for this entity instance
      entityInstanceDTO - the data transfer object containing this instance's data
      responseContentType - (optional) the response content type
      request - the request object, injected by Spring Boot
      Returns:
    • a 200-OK status with the updated entity instance on success
    • a 400-BAD_REQUEST status when no updatable fields are provided or the payload is invalid/fails schema validation
    • a 404-NOT_FOUND status when the project, entity type, or target instance cannot be found
    • a 410-GONE status when the project has ended or the entity type is marked as deprecated
    • a 422-UNPROCESSABLE_ENTITY status when the update failed

    • deleteEntityInstance

      @DeleteMapping("/projects/{projectAbbreviation}/entities/{entityTypeName}/{trustDeckId}") @PreAuthorize("hasRole(\'project-entity-instance-delete\')") public org.springframework.http.ResponseEntity<?> deleteEntityInstance(@PathVariable("projectAbbreviation") String projectAbbreviation, @PathVariable("entityTypeName") String entityTypeName, @PathVariable("trustDeckId") String trustDeckId, @RequestHeader(name="accept",required=false) String responseContentType, jakarta.servlet.http.HttpServletRequest request)
      Endpoint to delete an entity instance. Deletion is performed by tombstoning the instance through setting the is_deleted-flag accordingly.
      Parameters:
      projectAbbreviation - the abbreviation of the project to which the request is scoped to
      entityTypeName - the name of the entity type associated with this instance
      trustDeckId - the unique UUID for this entity instance
      responseContentType - (optional) the response content type
      request - the request object, injected by Spring Boot
      Returns:
    • a 204-NO_CONTENT status when the instance was successfully tombstoned
    • a 400-BAD_REQUEST status when the TrustDeckID is not a valid UUID
    • a 404-NOT_FOUND status when the project or entity type cannot be found
    • a 410-GONE status when the project has ended or the entity type is marked as deprecated
    • a 422-UNPROCESSABLE_ENTITY status when the deletion failed

    • searchEntityInstance

      @GetMapping(value="/projects/{projectAbbreviation}/entities/{entityTypeName}", params="query") @PreAuthorize("hasRole(\'project-entity-instance-search\')") public org.springframework.http.ResponseEntity<?> searchEntityInstance(@PathVariable("projectAbbreviation") String projectAbbreviation, @PathVariable("entityTypeName") String entityTypeName, @RequestParam(name="query",required=true) String query, @RequestHeader(name="accept",required=false) String responseContentType, jakarta.servlet.http.HttpServletRequest request)
      Endpoint to search for entity instances. Multi-word searches are supported.
      Parameters:
      projectAbbreviation - the abbreviation of the project to which the request is scoped to
      entityTypeName - the name of the entity type associated with this instance
      query - the search string that should be looked up
      responseContentType - (optional) the response content type
      request - the request object, injected by Spring Boot
      Returns:
    • a 200-OK status with the list of matching entity instances on success
    • a 206-PARTIAL_CONTENT status with a truncated result set when more than the maximum number of allowed results are found
    • a 404-NOT_FOUND status when the project or entity type cannot be found, or when no instances match the query
    • a 410-GONE status when the project has ended or the entity type is marked as deprecated

    • recordLinkage

      @PostMapping("/projects/{projectAbbreviation}/entities/{entityTypeName}/record-linkage") @PreAuthorize("hasRole(\'project-entity-instance-record-linkage\')") public org.springframework.http.ResponseEntity<?> recordLinkage(@PathVariable("projectAbbreviation") String projectAbbreviation, @PathVariable("entityTypeName") String entityTypeName, @RequestBody EntityInstanceDTO entityInstanceDTO, @RequestHeader(name="accept",required=false) String responseContentType, jakarta.servlet.http.HttpServletRequest request)
      Endpoint to check if there are entities in the database similar/equal to the given one.
      Parameters:
      projectAbbreviation - the abbreviation of the project to which the request is scoped to
      entityTypeName - the name of the entity type associated with the instance to check
      entityInstanceDTO - the data transfer object containing the data of the instance that should be checked
      responseContentType - (optional) the response content type
      request - the request object, injected by Spring Boot
      Returns:
    • a 200-OK status with a list of candidate entities when matches are found
    • a 204-NO_CONTENT status when no record-linkage candidates are found
    • a 400-BAD_REQUEST status when the instance payload is missing/empty or none of the required linkage attributes have values or are not defined at all, or when payload validation fails
    • a 404-NOT_FOUND status when the project or entity type does not exist
    • a 410-GONE status when the project has ended or the entity type is deprecated
    • a 422-UNPROCESSABLE_ENTITY status when the record-linkage search fails