Package eu.europeana.apikey.controller

Class ApiKeyController

  • @RestController
@RequestMapping("/apikey")
public class ApiKeyController
extends Object
    Handles all incoming requests Authentication is done using Keycloak authentication, but additional constraints my be checked (for example if the account is a manager account) Created by luthien on 18/04/2017. Major refactoring by M. Helinski and Patrick Ehlert in September-November 2019 Upgraded to java 11 & spring boot 2 by luthien in December 2019

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      org.springframework.http.ResponseEntity create​(ApiKeyRequest newKeyRequest)
      Create a new API key with the following mandatory values supplied in a JSON request body: - firstName - lastName - email - appName - company The following fields are optional: - website - sector The ApiKey field is generated as a unique and random 'readable' lowercase string 8 to 12 characters long, e.g.
      org.springframework.http.ResponseEntity createCaptcha​(javax.servlet.http.HttpServletRequest httpServletRequest, ApiKeyRequest newKeyRequest)
      Create a new API key with the following mandatory values supplied in a JSON request body: - firstName - lastName - email - appName - company The following fields are optional: - website - sector The ApiKey field is generated as a unique and random 'readable' lowercase string 8 to 12 characters long, e.g.
      org.springframework.http.ResponseEntity delete​(String id)
      This method deletes BOTH the apikey identified by the supplied string AND the linked Keycloak client.
      org.springframework.http.ResponseEntity deleteSynchronize​(String keycloakId)
      This method deletes ONLY the apikey identified by the linked Keycloak client ID aka "secret key".
      org.springframework.http.ResponseEntity disable​(String id)
      Disables / deprecates a given ApiKey.
      ApiKey enable​(String id)
      Re-enables a given invalid ApiKey (of which the deprecationdate column has previously been set to a past time).
      ApiKey read​(String id)
      Retrieves the details associated with the registration of a given ApiKey
      org.springframework.http.ResponseEntity synchronizeAllMissingClients()
      This method can be called by a system administrator to automatically create clients in Keycloak for all API keys that do not have a Keycloak client yet.
      org.springframework.http.ResponseEntity synchronizeMissingClient​(String apiKey)
      This method can be called by a system administrator to automatically create a client in Keycloak for the provided API key.
      ApiKey update​(String id, ApiKeyRequest apiKeyUpdate)
      Changes the registration details of an existing API key for the following public and non-generated values when supplied in the JSON request body: - firstName - lastName - email - company - appName - sector
      org.springframework.http.ResponseEntity validate​(javax.servlet.http.HttpServletRequest httpServletRequest)
      Validates a given ApiKey.

    • Method Detail

      • create

        @CrossOrigin(maxAge=600L)
@PostMapping(produces="application/json",
             consumes="application/json")
public org.springframework.http.ResponseEntity create​(@RequestBody
                                                      ApiKeyRequest newKeyRequest)
                                               throws ApiKeyException
        Create a new API key with the following mandatory values supplied in a JSON request body: - firstName - lastName - email - appName - company The following fields are optional: - website - sector The ApiKey field is generated as a unique and random 'readable' lowercase string 8 to 12 characters long, e.g. 'rhossindri', 'viancones' or 'ebobrent'; the secret key (Keyckoak ID) is generated by Keycloak. Upon successful execution, an email message containing those two fields will be sent to the email address supplied in the request.
        Parameters:
        newKeyRequest - requestbody containing supplied values
        Returns:
        JSON response containing the fields annotated with @JsonView(View.Public.class) in ApiKey.java HTTP 201 upon successful ApiKey creation HTTP 400 when a required parameter is missing or has an invalid value HTTP 401 in case of an invalid request HTTP 403 if the request is unauthorised HTTP 406 if a response MIME type other than application/JSON was requested HTTP 415 if the submitted request does not contain a valid JSON body HTTP 400 if apikey already exist for
        Throws:
        ApiKeyException

      • createCaptcha

        @CrossOrigin(maxAge=600L)
@PostMapping(path="/captcha",
             produces="application/json",
             consumes="application/json")
public org.springframework.http.ResponseEntity createCaptcha​(javax.servlet.http.HttpServletRequest httpServletRequest,
                                                             @RequestBody
                                                             ApiKeyRequest newKeyRequest)
                                                      throws ApiKeyException
        Create a new API key with the following mandatory values supplied in a JSON request body: - firstName - lastName - email - appName - company The following fields are optional: - website - sector The ApiKey field is generated as a unique and random 'readable' lowercase string 8 to 12 characters long, e.g. 'rhossindri', 'viancones' or 'ebobrent'; the secret key (Keyckoak ID) is generated by Keycloak. Upon successful execution, an email message containing those two fields will be sent to the email address supplied in the request. This method is protected with a captcha token that must be supplied in the Authorization header.
        Parameters:
        newKeyRequest - requestbody containing supplied values
        Returns:
        JSON response containing the fields annotated with @JsonView(View.Public.class) in ApiKey.java HTTP 201 upon successful ApiKey creation HTTP 400 when a required parameter is missing or has an invalid value HTTP 401 in case of an invalid request HTTP 403 if the request is unauthorised HTTP 406 if a response MIME type other than application/JSON was requested HTTP 415 if the submitted request does not contain a valid JSON body HTTP 400 if apikey already exist for
        Throws:
        ApiKeyException

      • read

        @CrossOrigin(maxAge=600L)
@GetMapping(path="/{id}",
            produces="application/json")
public ApiKey read​(@PathVariable("id")
                   String id)
            throws ApiKeyException
        Retrieves the details associated with the registration of a given ApiKey
        Parameters:
        id - string identifying the ApiKey's "public key"
        Returns:
        JSON response containing the fields annotated with @JsonView(View.Public.class) in ApiKey.java HTTP 200 upon successful execution HTTP 401 When reqested api key does not belong to the authenticated client or this client is not a manager client HTTP 404 when the requested ApiKey is not found in the database HTTP 406 if a MIME type other than application/JSON was requested
        Throws:
        ApiKeyException

      • update

        @CrossOrigin(maxAge=600L)
@PutMapping(value="/{id}",
            produces="application/json",
            consumes="application/json")
public ApiKey update​(@PathVariable("id")
                     String id,
                     @RequestBody
                     ApiKeyRequest apiKeyUpdate)
              throws ApiKeyException
        Changes the registration details of an existing API key for the following public and non-generated values when supplied in the JSON request body: - firstName - lastName - email - company - appName - sector
        Parameters:
        id - string identifying the ApiKey's "public key"
        apiKeyUpdate - RequestBody containing supplied values
        Returns:
        JSON response containing the fields annotated with @JsonView(View.Public.class) in ApiKey.java HTTP 200 upon successful ApiKey update HTTP 400 when a required parameter is missing HTTP 401 in case of an unauthorized request (client credential authentication fails) HTTP 403 if the request is unauthorised (when the client is not a manager) HTTP 404 if the apikey is not found HTTP 406 if a response MIME type other than application/JSON was requested HTTP 410 if the apikey is invalidated / deprecated HTTP 415 if the submitted request does not contain a valid JSON body
        Throws:
        ApiKeyException

      • disable

        @CrossOrigin(maxAge=600L)
@PutMapping(path="/{id}/disable")
public org.springframework.http.ResponseEntity disable​(@PathVariable("id")
                                                       String id)
                                                throws ApiKeyException
        Disables / deprecates a given ApiKey. This is achieved by: - setting the deprecationdate column of the given key to the current time; - disabling the linked Keycloak client Note that this method does not delete any data !
        Parameters:
        id - string identifying the ApiKey's "public key"
        Returns:
        HTTP 204 upon successful execution HTTP 401 in case of an invalid request HTTP 403 if the request is unauthorised HTTP 404 when the requested ApiKey is not found in the database HTTP 410 when the requested ApiKey is deprecated (i.e. has a past deprecationdate) Addionally, the field 'ApiKey-not-found' containing the string "apikey-not-found" will be available in the response header to help telling this HTTP 404 apart from one returned by the webserver for other reasons
        Throws:
        ApiKeyException

      • enable

        @CrossOrigin(maxAge=600L)
@PutMapping(path="/{id}/enable")
public ApiKey enable​(@PathVariable("id")
                     String id)
              throws ApiKeyException
        Re-enables a given invalid ApiKey (of which the deprecationdate column has previously been set to a past time). This is achieved by: - removing the contents of the deprecationdate column for this ApiKey; and - enabling the linked Keycloak client The code will execute regardless if the key is actually deprecated or not.
        Parameters:
        id - string identifying the ApiKey's "public key"
        Returns:
        JSON response containing the fields annotated with @JsonView(View.Public.class) in ApiKey.java HTTP 200 upon successful ApiKey update HTTP 400 when a required parameter is missing or has an invalid value HTTP 401 in case of an invalid request HTTP 403 if the request is unauthorised HTTP 404 if the apikey is not found HTTP 406 if a response MIME type other than application/JSON was requested HTTP 415 if the submitted request does not contain a valid JSON body
        Throws:
        ApiKeyException

      • delete

        @CrossOrigin(maxAge=600L)
@DeleteMapping(path="/{id}")
public org.springframework.http.ResponseEntity delete​(@PathVariable("id")
                                                      String id)
                                               throws ApiKeyException
        This method deletes BOTH the apikey identified by the supplied string AND the linked Keycloak client. NOTE: this actually deletes the apikey row from the database AND the linked Keycloak client, as opposed to disabling them!
        Parameters:
        id - string identifying the ApiKey's "public key"
        Returns:
        HTTP 204 upon successful execution HTTP 401 in case of an invalid request HTTP 403 if the request is unauthorised HTTP 404 when the requested keycloak identifier is not found in the database
        Throws:
        ApiKeyException

      • deleteSynchronize

        @CrossOrigin(maxAge=600L)
@DeleteMapping(path="/synchronize/{keycloakid}")
public org.springframework.http.ResponseEntity deleteSynchronize​(@PathVariable("keycloakid")
                                                                 String keycloakId)
                                                          throws ForbiddenException
        This method deletes ONLY the apikey identified by the linked Keycloak client ID aka "secret key". NOTE: this actually deletes the apikey row in the database, as opposed to disabling the apikey. This method may be executed only by the privileged client during the synchronization procedure in Keycloak.
        Parameters:
        keycloakId - Keycloak ID aka "secret key"
        Returns:
        HTTP 204 upon successful execution HTTP 401 in case of an invalid request HTTP 403 if the request is unauthorised HTTP 404 when the requested keycloak identifier is not found in the database
        Throws:
        ForbiddenException

      • synchronizeAllMissingClients

        @PostMapping(path="/synchronize/missingClient/all")
public org.springframework.http.ResponseEntity synchronizeAllMissingClients()
                                                                     throws ApiKeyException
        This method can be called by a system administrator to automatically create clients in Keycloak for all API keys that do not have a Keycloak client yet. This will be used during the migration from the old apikey database to a new one with Keycloak as backend.
        Throws:
        ApiKeyException

      • synchronizeMissingClient

        @PostMapping(path="/synchronize/missingClient/{apiKey}")
public org.springframework.http.ResponseEntity synchronizeMissingClient​(@PathVariable
                                                                        String apiKey)
                                                                 throws ApiKeyException
        This method can be called by a system administrator to automatically create a client in Keycloak for the provided API key. WARNING: this will replace the existing client secret with a new one!
        Throws:
        ApiKeyException

      • validate

        @PostMapping(path="/validate")
public org.springframework.http.ResponseEntity validate​(javax.servlet.http.HttpServletRequest httpServletRequest)
                                                 throws ApiKeyException
        Validates a given ApiKey. Sets last access date and activation date (if not set, ie. first access) with the current date and +1 increments the usage count of this ApiKey.
        Parameters:
        httpServletRequest - request
        Returns:
        HTTP 204 upon successful validation HTTP 400 bad request when header does not contain api key HTTP 401 in case of an unregistered api key HTTP 410 when the requested ApiKey is deprecated (i.e. has a past deprecationdate)
        Throws:
        ApiKeyException