API Reference
The MBP REST API is documented using the OpenAPI specification. The OpenAPI document is created automatically and can be accessed when the MBP is started. A Swagger UI is also automatically created and available when the MBP is running.
- OpenAPI document:
http://[MBP-Host]:8080/MBP/v2/api-docs - Swagger UI:
http://[[MBP-Host]:8080/MBP/swagger-ui.html
As the admin user, it is also possible to access them through Main Navigation > Settings > REST API Documentation.
Most endpoints of the API are restricted to authenticated users and cannot be used anonymously. The only exceptions are those endpoints that are necessary for the registration of new users and their authentication. Formerly, users could authenticate themselves at the MBP by adding their credentials (username and password) as base64-encoded strings to the HTTP headers of all requests, as it is intended by the basic access authentication method of HTTP. However, through Pull Request #588, the user system of the MBP changed: Now the MBP explicitly keeps track of user session by applying the database session state pattern, leading to a stateless and thus scalable application. When a user logs into the MBP, a session ID with limited lifetime is generated for this user and stored in the database. In order to authenticate itself against the MBP, the user needs to wrap this session ID into a HTTP cookie and embedd it into every subsequent HTTP request that is performed against the REST API of the MBP. On the basis of this cookie, the MBP is able to look up the pertained user and authenticate its HTTP requests. The MBP supports multiple simultaneously active sessions of the same user and automatically invalidates all sessions 7 days after their creation.
In order to authenticate your HTTP requests against the REST API of the MBP, please follow the subsequently listed steps:
Step 0:
Create a new user account that is supposed to be used for the authentication. This can be done either via the REST API or the web interface of the MBP.
Step 1:
Perform a login request by providing the username and the password of the previously created user and check out the returned cookie information:
curl --cookie-jar - -d '{"username":"admin", "password":"12345"}' -H "Content-Type: application/json" -X POST http://localhost:8080/MBP/api/users/login
Response:
{"id":"607db9061d2ce90bb4b6131a","username":"admin","firstName":"admin","lastName":"admin","isSystemUser":true,"isLoginable":true,"loginable":true,"entityType":"REQUESTING_ENTITY","isAdmin":true}# Netscape HTTP Cookie File
# https://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.
#HttpOnly_localhost FALSE / FALSE 1625929368 user_session 60c229bf2924b101415a0001
This response contains a cookie with name user_session. This cookie carries the session ID that was generated by the MBP for the user.
Step 2:
This cookie can now be used to authenticate the subsequent HTTP requests. In the following, this is exemplarily demonstrated for a GET request which intends to retrieve all currently registered devices of the user from the MBP. Make also sure to add the required access policy information to the HTTP headers of all requests.
curl -H "X-MBP-Access-Request: requesting-entity-firstname=admin;;requesting-entity-lastname=admin;;requesting-entity-username=admin" --cookie "user_session=60c229bf2924b101415a0001" http://localhost:8080/MBP/api/devices
Response:
{"_embedded":{"devices":[{"defaultEntity":false,"accessControlPolicyIds":[],"created":1620876612940,"lastModified":1620876612940,"id":"609c9d449672bb5e7177f218","name":"TESTING_Device","componentType":"Computer","ipAddress":"192.168.221.167","date":null,"username":"ubuntu","entityType":"REQUESTED_ENTITY","usesPassword":true,"usesRSAKey":false,"wasModelled":false,"ownerName":null,"_links":{"self":{"href":"http://localhost:8080/MBP/609c9d449672bb5e7177f218"}}}],"_links":{"self":{"href":"http://localhost:8080/MBP/api/devices"}},"page":{"size":2000,"totalElements":4,"totalPages":1,"number":0}}}
