Copyright © 2005-2022

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Overview

This guide describes the RESTful API of the OpenWMS.org UAA (User Authentication & Administration) module and its usage. Some general terms and definitions are explained and declared in the first part of the document whereas in the second part the usage of the API is shown in a more use-case-driven approach.

Resources

A description of all used API resources.

Representation Formats

Basically JSON is used as representation format by default if not otherwise requested or mentioned below. XML format is supported for the index pages as well, but must be requested explicitly. Furthermore a vendor specific JSON format is used to represent resource representations. Therefore it’s absolutely required the Accept header denotes the demanded type. Find the type in the examples below.

Dates in JSON

Date or datetime fields are not treated specially in JSON. Within the scope of this API a date or datetime field is always expected and rendered as JSON String in ISO8601 format with timezone information and milliseconds: yyyy-MM-dd’T’HH:mm:ssXXX.

Embedded Entities

For the sake of convenience some response entities may included embedded entities or even parts of it. A reference to the actual entity is provided as HAL link as well.

Error Responses

Beside the actual representation of resources, the server may result an error response in JSON format that contains basic information about the error occurred. This information is additional to the standard HTTP status code and may help clients to identify the error cause in order to re-phrase and send the request again.

Currently there are two types of errors with their own response formats.

Server Declined Errors

This kind of errors are sent by the server runtime environment even before the request had a chance to be processed.

An example response looks like this:

{
    "timestamp": 1512400854941,
    "status": 500,
    "error": "Internal Server Error",
    "exception": "org.ameba.oauth2.InvalidTokenException",
    "message": "JWT expired at 2017-12-04T15:04:43Z. Current time: 2017-12-04T15:20:54Z, ...",
    "path": "/v1/transport-units?bk=00000000000000004711"
}

The JSON structure contains the following fields.

Property Name Description

timestamp

When the error occurred on server side

status

The http status of the error

error

A short error text

exception

Internal class name of the Java exception type

message

A more descriptive error text describing the error in detail

path

The part of the URI for the REST resource that was queried

API Declined Errors

Those errors are thrown within the REST API validation and processing logic. For example, if a client request does not match the expected format or has produced an error on server side, the API will decline the request and return a response with status client-side error (4xx).

The structure of the response is aligned to the RFC7808. An example response looks like this:

{
    "message": "LocationGroup with name [NOT_EXISTS] not found",
    "messageKey": "owms.common.common.lg.notFoundByName",
    "obj" : [ "NOT_EXISTS" ],
    "httpStatus" : "404",
    "class" : "String"
}

The JSON structure contains the following fields.

Property Name Description

message

A short error text

messageKey

An unique identifier across the API that can be used to identify and translate the error message on the client side

obj

An array of possible passed arguments to the message

httpStatus

The http status of the error

class

The arguments type

Following message keys are currently used:

Message Key Description Action

not.found

The requested resource has not been found

The resource does not exist anymore or has never existed. The resource identifier must be verified

Index

The initial HTTP request to retrieve information about all available resources looks like the following. The Index page is a public available resource and does not need any authentication.

Unresolved directive in 1-index.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/get-index/http-request.adoc[]

The Index resource is returned in the response body with the response status of 200-OK. This main Index lists all primary resource entities to follow next.

Unresolved directive in 1-index.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/get-index/http-response.adoc[]

A client application only needs to know about the agreed link names and follow the corresponding href link to navigate to further resources.

User

A User represents a human user of the system, usually in front of an UI who interacts with the system. User representations can be created, modified and retrieved. An User is also allowed to authenticate against an UAA endpoint.

User Index

An overview of all possible operations on Users can be found on the User index page that is retrieved with a GET request: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/users-index/http-request.adoc[]

And the server responds with a HAL+JSON representation to further operations: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/users-index/http-response.adoc[]

Create an User

To create a new User instance, a POST request must be send to the server with the mandatory fields of the User resource in the request body. Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-create/http-request.adoc[] Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-create/request-fields.adoc[]

If the User has been created successfully, the server returns the URI to the created resource in the Location header: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-create/http-response.adoc[]

If an User with the same name already exists the server returns an error: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-create-exists/http-response.adoc[]

Find all Users

To find and retrieve an array of all existing Users a client may call a GET request: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findAll/http-request.adoc[]

and returns either an array of Users…​ Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findAll/http-response.adoc[]

or an empty array, but always with a 200-OK. Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findNone/http-response.adoc[]

Find an User by persistent key

A newly created User can be retrieved by following the URI in the Location header of the response. This URI points to the created resource: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findByPkey/http-request.adoc[]

If the resource exists the server responds with a 200-OK and the User representation in the response body. Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findByPkey/http-response.adoc[]

Find all Roles that are assigned to a User

A client might ask for all Roles that are assigned to a User resource. Therefore the client needs to query all roles of the primary User: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findRolesOfUser/http-request.adoc[]

and get an array of Roles back, that could also be empty: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findRolesOfUser/http-response.adoc[]

Find all Grants that belong to a User

A client might ask for all Grants that are assigned to a User resource. Therefore the client needs to query all grants of the primary User: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findGrantsOfUser/http-request.adoc[]

and get an array of Grants back, that could also be empty: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-findGrantsOfUser/http-response.adoc[]

Modify an existing User

An existing User instance can be modified by sending a PUT request with the User representation as request body. Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-save/http-request.adoc[]

If the server has correctly updated the User the response is a: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-save/http-response.adoc[]

Change the Users password

Send a POST request to the Users password attribute to set or change the password of an that User. Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-change-password/http-request.adoc[]

If the server has successfully set the password the response looks like: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-change-password/http-response.adoc[]

Update the image of an existing User

To set the image of an existing User a client needs to send a PATCH request along the image in the UserDetails. Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-saveimage/http-request.adoc[]

If the server has correctly updated the Users image the response looks like: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-saveimage/http-response.adoc[]

Delete an User

To finally delete all User data a DELETE request with the persistent key of the User is required: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-delete/http-request.adoc[]

If the User is not assigned somewhere else (in Roles) and it has been deleted successfully the server responds: Unresolved directive in 2-users.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/user-delete/http-response.adoc[]

Role

An User could be assigned to multiple Roles and act on behalf of a Role. Additionally a Role assigns Grants to all the Users that are assigned to this Role. By doing so, a Role is also a group of Grants that can be assigned to multiple Users.

Role Index

An overview of all possible operations on Roles can be found on the Role index page that is retrieved with a GET request: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/roles-index/http-request.adoc[]

And the server responds with a HAL+JSON representation to further operations: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/roles-index/http-response.adoc[]

Create a Role

To create a new Role instance, a POST request must be send to the server with the mandatory fields of the Role resource in the request body. Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-create/http-request.adoc[] Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-create/request-fields.adoc[]

If the Role has been created successfully, the server returns the URI to the created resource in the Location header: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-create/http-response.adoc[]

If a Role with the same name already exists the server returns an error: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-create-exists/http-response.adoc[]

Find all Roles

To find and retrieve an array of all existing Roles a role may call a GET request: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-findAll/http-request.adoc[]

and returns either an array of Roles or an empty array, but always a 200-OK. Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-findAll/http-response.adoc[]

Find a Role by persistent key

Each Role has an unique ID the pKey or persistent identifier. To find and return a Role by pKey a client must send a GET request to the Roles resource: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-findByPKey/http-request.adoc[] Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-findByPKey/http-response.adoc[]

Find all Users that are assigned to a Role

A client might ask for all Users that are assigned to a Role resource. Therefore the client needs to query all users of the primary Role: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-findUsersOfRole/http-request.adoc[]

and get an array of Users back, that could also be empty: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-findUsersOfRole/http-response.adoc[]

Find all Grants that belong to a Role

A client might ask for all Grants that are assigned to a Role resource. Therefore the client needs to query all grants of the primary Role: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-findGrantsOfRole/http-request.adoc[]

and get an array of Grants back, that could also be empty: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-findGrantsOfRole/http-response.adoc[]

Modify an existing Role

An existing Role instance can be modified by sending a PUT request with the Role representation as request body. At least the name of the Role, as an identifying attribute must be set. Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-save/http-request.adoc[] Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-save/request-fields.adoc[]

If the server has correctly updated the Role the response contains the updated representation: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-save/http-response.adoc[]

If the name of the Role to update is missing, the server responds with an error: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-save-noname/http-response.adoc[]

Assign an User to a Role

Users can be assigned to one or more Roles. To assign an existing User to an existing Role the client must send a POST request to the primary Role resource: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-assign-user/http-request.adoc[]

If the User has been assigned successfully, the server responds with 200-OK: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-assign-user/http-response.adoc[]

If the User or the Role do not exist the server responds with an error: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-assign-unknown-user/http-response.adoc[]

Unassign an User from a Role

Already assigned Users can be unassigned from a Role. Therefore the client sends a DELETE request on the secondary User resource of the primary Role resource. Note: This will not delete the User but delete the assignment between the Role and the User. Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-unassign-user/http-request.adoc[]

If the User has been unassigned successfully, the server responds with 200-OK: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-unassign-user/http-response.adoc[]

If the User or the Role do not exist the server responds with an error: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-unassign-unknown-role/http-response.adoc[]

Delete a Role

To finally delete all Role data, a DELETE request with the persistent key of the Role is required: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-delete/http-request.adoc[]

If the Role has been deleted successfully the server responds: Unresolved directive in 3-roles.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/role-delete/http-response.adoc[]

Grant

A Grant represents a permission to perform an action. A Grant can be assigned to a Role and is always tied to some kind of action that can be taken. It has a unique business key, that is used in API or UI to protect against unauthorized access.

Grant Index

An overview of all possible operations on Grants can be found on the Grant index page that is retrieved with a GET request: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grants-index/http-request.adoc[]

And the server responds with a HAL+JSON representation to further operations: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grants-index/http-response.adoc[]

Create a Grant

To create a new Grant instance, a POST request must be send to the server with the mandatory fields of the Grant resource in the request body. Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-create/http-request.adoc[]

Not named properties are optional to pass. Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-create/request-fields.adoc[]

If the Grant has been created successfully, the server returns the URI to the created resource in the Location header: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-create/http-response.adoc[]

If a Grant with the same name already exists the server returns an error: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-create-exists/http-response.adoc[]

Find all Grants

To retrieve all existing Grants from the server, a client simply needs to do a GET request to the Grants resource. Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findall/http-request.adoc[]

The server responds with a list representation of all Grants or an empty list: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findall/http-response.adoc[]

Find a Grant by persistent key

Each Grant has an unique ID the pKey or persistent identifier. To find and return a Grant by pKey a client must send a GET request to the Grants resource: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findbypkey/http-request.adoc[] Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findbypkey/http-response.adoc[] Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findbypkey/response-fields.adoc[]

Find all Grants of a User

To retrieve all existing Grants from assigned to a User, a client simply needs to do a GET request to the Grants resource and pass the users identity within the X-Identity http header. Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findallforuser/http-request.adoc[]

The server responds with a list representation of all Grants: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findallforuser/http-response.adoc[]

or a HTTP 204-NO CONTENT response if no Grants are assigned to the User: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findallforuser-empty/http-response.adoc[]

or a HTTP 404-NOT FOUND response if the User does not exist: Unresolved directive in 4-grants.adoc - include::/home/runner/work/org.openwms.core.uaa/org.openwms.core.uaa/target/generated-snippets/grant-findallforuser-404/http-response.adoc[]