API Documentation

Entity-Relationship Model

All API entities have been documented in detail in an Entity-Relationship Model (ERM). This model provides a visual representation of the relationships and structures of entities within the application. The file was created in drawio format and can be directly used in draw.io to further edit or analyze the structures. It can be downloaded via the following button.

More information about draw.io and how to open the file can be found on the official website: drawio.com.

API Documentation

The full API documentation is accessible via Swagger UI. All publicly available GET methods and paths that contain '/public/' as well as all other GET requests, except those related to the User entity, are freely accessible. By logging in with the guest user credentials, additional access to the 'current user' endpoint is granted. The login process consists of several steps, which are described below.

Please note that the Swagger interface is not optimized for mobile devices. It is recommended to use a device with at least a laptop-sized screen for a better user experience.

1. Step 1

   

   The login process begins with the following step: First, follow the link to the Swagger interface. There, locate the CSRF endpoint of the gateway server. Expand this endpoint to reveal the 'Try Out' button. After clicking 'Try Out', press 'Execute'. If the gateway server has not yet set an XSRF-TOKEN in the cookies, it will be set now. Once this is done, the token will be available after reloading the page. After completing this step, navigate to the 'Java Spring Server' to continue with the following steps.

2. Step 2

   

   Now, open the developer tools in the browser by right-clicking and selecting 'Inspect'. Then, go to the 'Application' tab and select 'Cookies'. In the list of cookies, find the entry 'XSRF-TOKEN' and copy its value. Once the XSRF-TOKEN value is copied, close the developer tools. Return to the Swagger interface and click 'Authorize'. In the CSRF token input field, paste the copied token, click 'Authorize', and then close the window.

3. Step 3

   

   Scroll down to the Token endpoints and open the 'Login' POST request. In the request body, enter the username 'guest' and the password 'GuestUser1234!' instead of the placeholder values. Ensure that both the username and password are enclosed in quotation marks and separated by a colon. A comma must follow the username, as shown in the example image. Then, click 'Execute'.

4. Step 4

   

   If the request is successful, the response will contain an access token. Copy the token value (without quotation marks). This access token is a JWT (JSON Web Token). Additionally, a JWT refresh token has been stored as an Http-only cookie. The name of this cookie is 'sonastan-refresh-token', and it can be viewed in the cookies (see reference Step 2 for viewing the cookie).

   The content of the access token and refresh token can be viewed at jwt.io For more information and a detailed explanation of how JWT works, refer to the jwt.io-API Documentation.

5. Step 5

   

   Now scroll back up to the top of the page and click 'Authorize'. In the 'Access Auth' input field, paste the previously copied access token. Then click 'Authorize' and 'Close'. You are now officially logged in and can execute authorized API requests. The access token is valid for 10 minutes.

6. Step 6

   

   After successful login, the 'Current User' GET request can be executed under the user endpoints. This allows you to retrieve the user data of the currently logged-in user, verifying that the login was successful and access is working properly.

7. Step 7

   

   If the access token expires or a new access token is needed, the value of the 'sonastan-refresh-token' cookie must be copied. See reference Step 2 for viewing the cookie value. Once the refresh token is copied, navigate to the Token endpoints and open the Refresh POST request. Click 'Try Out'. In the 'sonastan-refresh-token' input field, paste the copied token and then click 'Execute'. If the request is successful, a new access token is received, and a new 'sonastan-refresh-token' value is stored in the cookies. The new refresh token is valid for 2 days.