REST API

You can integrate LUY with other repositories or planning tools by using its REST API. A tool or integrating component can access the building block data (using the single element API or massdata API), the metamodel (using the metamodel API), the building block history data (using the history API) as well as attributes, attribute groups, users and roles (using the administration API).

A documentation of REST endpoints (including examples and model definitions) using the open API specification can be found here: Swagger UI

Authentication

Authentication is required in order to access most of the REST API endpoints. Clients are encouraged to use basic access authentication (RFC-7617):

BASH

curl -u "user:password" -X GET "<LUY_URL>/api/element/BusinessProcess/{ID}"

Reusing a user session

Every time a request is sent to the REST API without an existing session, a new session is started and initialized with the required setup data. REST API sessions which are no longer in use will time out after 5 minutes by default.

When performing a lot of API requests, it is advised to reuse an existing session as this has a beneficial effect on both the request time and the required memory of the LUY instance. A session can be reused by sending the JSESSIONID cookie received in response to the first authentication request:

CODE

# Obtain session cookie and save it in cookies.txt, any API endpoint can be used for this
curl -u "user:password" --cookie-jar cookies.txt --head "<LUY_URL>/api/auth-scheme"

# Reuse an existing session by sending the session cookie in subsequent requests
curl -b cookies.txt -X GET "<LUY_URL>/api/element/BusinessProcess/{ID}"

CSRF protection

LUY uses a “cookie-to-header token” pattern to protect against CSRF attacks. If CSRF protection is enabled, modifying requests (PATCH, POST, PUT, DELETE), which reuse an existing user session, must also include the XSRF-TOKEN cookie and X-XSRF-TOKEN header. The XSRF-TOKEN cookie is delivered along with the session in response to the authentication request and is valid for the lifetime of the session. The X-XSRF-TOKEN header must be added manually by the client and its value must be the same as the value of the XSRF-TOKEN cookie.

BASH

# Obtain session cookie and save it in cookies.txt, any API endpoint can be used for this
curl -u "user:password" --head "<LUY_URL>/api/auth-scheme" --cookie-jar cookies.txt

# Reuse session and csrf token cookies and include X-XSRF-TOKEN header
curl -b cookies.txt \
     -H "X-XSRF-TOKEN: $(grep XSRF-TOKEN cookies.txt | awk 'NF{ print $NF }')" \ # Extract the value of XSRF-TOKEN cookie
     -H "Content-Type: application/json" \
     -d "{\"name\" : [\"Test\"]}" \
     -X PUT "<LUY_URL>/api/element/BusinessProcess/4205"