Copyright © 2005-2020

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 WMS Receiving Service 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:ss.SSSTZD.

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": "COMMON.LOCATION_GROUP_NOT_FOUND",
    "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.

GET /index HTTP/1.1
Host: localhost:8080

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.

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 347

{
  "_links" : {
    "user-index" : {
      "href" : "http://localhost:8080/users/index"
    },
    "role-index" : {
      "href" : "http://localhost:8080/roles/index"
    },
    "grant-index" : {
      "href" : "http://localhost:8080/grants/index"
    },
    "client-index" : {
      "href" : "http://localhost:8080/api/clients/index"
    }
  }
}

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.

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 in the request body

POST /users HTTP/1.1
Content-Type: application/json
Content-Length: 77
Host: localhost:8080

{
  "links" : [ ],
  "username" : "admin2",
  "email" : "admin@example.com"
}
Path Type Description

username

String

The unique name of the User in the system

email

String

The email address used by the User, unique in the system

If the User has been created successfully, the server returns the URI to the created resource in the Location header:

HTTP/1.1 201 Created
Location: http://localhost:8080/users/06c66b5b-c137-4473-b57c-6bb4434ac45e/
Content-Type: application/hal+json
Content-Length: 144

{
  "pKey" : "06c66b5b-c137-4473-b57c-6bb4434ac45e",
  "username" : "admin2",
  "externalUser" : false,
  "locked" : false,
  "enabled" : true
}

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:

GET /users/06c66b5b-c137-4473-b57c-6bb4434ac45e/ HTTP/1.1
Host: localhost:8080

If the resource exists the server responds with a 200-OK and the User representation in the response body.

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 144

{
  "pKey" : "06c66b5b-c137-4473-b57c-6bb4434ac45e",
  "username" : "admin2",
  "externalUser" : false,
  "locked" : false,
  "enabled" : true
}

Get the User Details (OAuth2 UserDetails)

An endpoint exists to get the details of the current logged-in User from. An OAuth2 Access Token must be provided as Bearer token in order to access the endpoint.

GET /oauth/userinfo HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDYxMjIyMzUsInVzZXJfbmFtZSI6InRlc3RlciIsImp0aSI6IjVmNjljYmQ3LWVhNTQtNDVlOC1iNGIyLTllYmM4YzAyYzk5ZiIsImNsaWVudF9pZCI6ImdhdGV3YXkiLCJzY29wZSI6WyJnYXRld2F5Il19.yQ8JdMi8x_IJ90qWqWJERTrwBp35KTIIZ1MpB4Qyekk
Host: localhost:8080

If the access token is valid and the server granted access to the resource, a JSON object with the user details is returned.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 307
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
  "sub" : "tester",
  "gender" : "FEMALE",
  "name" : "tester",
  "phone_number" : "001-1234-56789",
  "given_name" : "Mister Jenkins",
  "family_name" : "Mister Jenkins",
  "email" : "tester.tester@example.com",
  "picture" : "http://localhost:8080/uaa/user/96baa849-dd19-4b19-8c5e-895d3b7f405d/image/"
}
Path Type Description

sub

String

Subject is the logged in end-user

gender

String

The end-users gender

name

String

Name of the end-user

phone_number

String

Her phone number

given_name

String

The given name

family_name

String

Her family name

email

String

Her primary email address

picture

String

A link to a profile picture

Delete an User

To finally delete all User data a DELETE request to the persistent key of the User is required:

DELETE /users/06c66b5b-c137-4473-b57c-6bb4434ac45e/ HTTP/1.1
Host: localhost:8080

If the User is not assigned somewhere else (in Roles) and it has been deleted successfully the server responds:

HTTP/1.1 204 No Content