API — User Operations

This guide contains all API operations related to users.

Register a User

The first action to perform should be to register the user. We’ll make use of the access_token copied in the previous section to make an authenticated API call to the /register endpoint.

Tip

This API will not be needed once the front-end application is used. The front-end application will automatically make this call once a user has made a new account registration on the front-end application.

The access_token contains various claims within the token. These include:

• preferred_username
• email
• given_name
• family_name

These values are decrypted in the back-end application and used to insert a new user object into the database. A unique userID will be generated upon successful insertion of the new user. This “localized” userID value is used throughout the application to keep track of user specific data.

1. Perform a GET request:

   curl -v --location 'http://localhost:8080/register' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

2. This should provide a response like:

   * Host localhost:8080 was resolved.
   * IPv6: ::1
   * IPv4: 127.0.0.1
   *   Trying [::1]:8080...
   * Connected to localhost (::1) port 8080
   > GET /register HTTP/1.1
   > Host: localhost:8080
   > User-Agent: curl/8.6.0
   > Accept: */*
   > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....
   >
   < HTTP/1.1 201
   < Vary: Origin
   < Vary: Access-Control-Request-Method
   < Vary: Access-Control-Request-Headers
   < X-Content-Type-Options: nosniff
   < X-XSS-Protection: 0
   < Cache-Control: no-cache, no-store, max-age=0, must-revalidate
   < Pragma: no-cache
   < Expires: 0
   < X-Frame-Options: DENY
   < Content-Length: 0
   * Connection #0 to host localhost left intact

3. There is no response body, and the HTTP status code is HTTP 201 Created

Retrieve a list of all Users

In order to retrieve a list of all users in the system make an authenticated API call to the /users endpoint.

Note

The role required to execute this endpoint is SYS_ADMIN. In the future when the users feature overhaul happens this endpoint will be reworked and extended so that users can search for other users with a caveat being that a user will be able to exclude themselves from global public searches.

1. Perform a GET request:

   curl --location 'http://localhost:8080/users' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

2. This should provide a response like:

   [
     {
       "userID": "1c529433-063f-40c2-8dba-4d5a8197fd5b",
       "username": "walthersmulders",
       "emailAddress": "[email protected]",
       "firstName": "Walther",
       "lastName": "Smulders"
     }
   ]

3. Take note of the userID value and copy it, in the next section you’ll make use of that value to update the user.

Update a User by UserID

In order to update a specific user’s details, it is required to pass in the userID as a path parameter. In this case, take the userID value from the previous section: 1c529433-063f-40c2-8dba-4d5a8197fd5b.

You’ll see that there is no request body attached with the request. This is because the same principles apply that you find in the /register (register user) endpoint.

Note

The access_token contains various claims within the token. When the front-end application is in use this request will automatically happen. The user’s details are updated on the identity provider (Keycloak) and synchronized with the back-end application by virtue of making use of the claims in the token.

For the purpose of this guide, I have logged into the Keycloak server and changed the surname value for the user from Smulders to UpdatedSurname. In order for the access_token to retrieve the latest information, I performed another login and subsequently updated the token in the requests.

Again, this will be handled automatically once the front-end application is integrated and released. I will also update this guide when that happens.

1. Perform a PUT request:

   curl --location --request PUT 'http://localhost:8080/users/1c529433-063f-40c2-8dba-4d5a8197fd5b' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

2. This should provide a response like:

   [
     {
       "userID": "1c529433-063f-40c2-8dba-4d5a8197fd5b",
       "username": "walthersmulders",
       "emailAddress": "[email protected]",
       "firstName": "Walther",
       "lastName": "UpdatedSurname"
     }
   ]

3. Take note of the lastName value. It has been updated from Smulders to UpdatedSurname

Get a User by UserID

In order to retrieve a specific user’s details, it is required to pass in the userID as a path parameter. In this case, take the userID value from the previous section: 1c529433-063f-40c2-8dba-4d5a8197fd5b.

Note

The role required to execute this endpoint is USER. This means each user can execute this endpoint in order to retrieve their details.

1. Perform a GET request:

   curl --location 'http://localhost:8080/users/1c529433-063f-40c2-8dba-4d5a8197fd5b' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

2. This should provide a response like:

   {
     "userID": "1c529433-063f-40c2-8dba-4d5a8197fd5b",
     "username": "walthersmulders",
     "emailAddress": "[email protected]",
     "firstName": "Walther",
     "lastName": "UpdatedSurname"
   }

3. The response is a single User object.

Summary

Endpoints covered in this guide are as follows:

• GET /users/register
  • Registers the new user in the back-end database
• GET /users
  • Retrieve all users in the system
• PUT /users/<userID>
  • Update a specific user based on the userID value
• GET /users/<userID>
  • Retrieve a single user based on the userID value