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.
The access_token
contains various claims within the token. These include:
- preferred_username
- 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.
-
Perform a
GET
request:Terminal window curl -v --location 'http://localhost:8080/register' \--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' -
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 -
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.
-
Perform a
GET
request:Terminal window curl --location 'http://localhost:8080/users' \--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' -
This should provide a response like:
[{"userID": "1c529433-063f-40c2-8dba-4d5a8197fd5b","username": "walthersmulders","firstName": "Walther","lastName": "Smulders"}] -
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.
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.
-
Perform a
PUT
request:Terminal window curl --location --request PUT 'http://localhost:8080/users/1c529433-063f-40c2-8dba-4d5a8197fd5b' \--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' -
This should provide a response like:
[{"userID": "1c529433-063f-40c2-8dba-4d5a8197fd5b","username": "walthersmulders","firstName": "Walther","lastName": "UpdatedSurname"}] -
Take note of the
lastName
value. It has been updated fromSmulders
toUpdatedSurname
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
.
-
Perform a
GET
request:Terminal window curl --location 'http://localhost:8080/users/1c529433-063f-40c2-8dba-4d5a8197fd5b' \--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' -
This should provide a response like:
{"userID": "1c529433-063f-40c2-8dba-4d5a8197fd5b","username": "walthersmulders","firstName": "Walther","lastName": "UpdatedSurname"} -
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
- Update a specific user based on the
GET /users/<userID>
- Retrieve a single user based on the
userID
value
- Retrieve a single user based on the