HTTP Methods

The Rest Docs API follows standard HTTP and REST conventions as closely as possible in its exposure of resources as end-points and use of HTTP methods (verbs).

HTTP Method Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource

DELETE

Used to delete an existing resource

HTTP status codes

The Rest Docs API follows standard HTTP and REST conventions as closely as possible in it’s use of HTTP status codes.

2xx - Success codes

Status code Usage

200 OK

The request completed successfully

4xx - Client side error

Status code Usage

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

Either wrong credentials or no credentials provided

403 Forbidden

The user is not authorized to perform the operation

404 Not Found

The requested resource does not exist

422 Unprocessable Entity

The requested has invalid or missing parameters

See the error handing section for examples

5xx - Server side error

Status code Usage

500 Internal Server error

An unexpected error occurred on the server

Login

To login to the api you will use your Transition Manager user name and password.

Login (POST /api/login)

A POST request will log you into the API and give an authentication access token to use for future requests.

Request Parameters/JSON body

Path Type Required Description

username

String

true

The users username for login.

password

String

true

The users password.

 
{
  "username" : "me",
  "password" : "password"
}

Example request

$ curl 'http://api.restdocs.com/api/login' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json; charset=UTF-8' \
    -d '{
  "username" : "me",
  "password" : "password"
}'

Response structure

Path Type Required Description

access_token

String

true

The access token to use for authentication on REST requests.

username

String

true

The username that was used to get an access token for.

roles

Array

true

The roles that the user has, giving them access to the application.

token_type

String

true

The type of token which is always Bearer.

expires_in

Number

true

How long the access token in good for in seconds.

refresh_token

String

true

Another token that can be used to get a new token.

Example success response

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Content-Length: 2498
Date: Mon, 28 Jun 2021 04:51:57 GMT
Keep-Alive: timeout=60
Connection: keep-alive

{
  "username" : "me",
  "roles" : [ "ROLE_ACTUATOR", "ROLE_ADMIN", "ROLE_USER" ],
  "token_type" : "Bearer",
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJwcmluY2lwYWwiOiJINHNJQUFBQUFBQUFBSlZTc1c0VFFSUjh2amdLRUJFU0pKQW9Ra1BvMEZtQzBwVmpEQUlkTnJKOVRaQkE2N3VYWTVPOTNjdnVYbUkzeUJVVUtZS0FTRWo4UXY0RUdqNEFRVUdibWc3eDltem5ERTNFVnFmWnVabDViXC9ia0ZCYU5obnVKWmx3WVB4TjV3cVZ2TXMxbFlqREtOYmNqUHplb1k3UUY0MkZCREFtQnlhbDRVQW5BNDdHRnE4RU8yMmMxd1dSUzZ3eDJNTEwxb1lhN1NpZFR4VzNOVWp4UWV0Y1wvMDQ2VXhyOE1TdW5LYncrV3RtQ05SWkhLcFcwcjJScG1YR084QmFzbEZxaG8xMEhYSXJwQmFUa1RacDY2aEpJTkJNWUJMTFBjdmxUa3l0Rll1RElKbTFzdWFqMjA5UUF1Wk13WVN2ZlBKRDNyb3J0N0YxUFNCSHZ3Q3FyRHJFS0hkbmZiVVgybjR6ZVZFRFExVjlKc2hESlZNZFwvbXpwejB4K3Z2dmg1OUdvY2VBTzNrenZuXC9sUGlOVFJoXC9mdjdyWnJIb1NtVGgrbHowa2xZZlpwUm1yVlR1YTNUTzN6NCtmWDk4K3ViWkFqazd4b1BcLzcyT2pNZDNjcUtuU2pHbG0xVnhISkh0UXBlOEZFdDg4WDN6V3dzanY4VFFUU0M5S1dvelBMRXBoR3JlcWxaanQyOExsYmlkb3ZXZzArMkdqMytrYWg2OVl1RFJCN3o5NTFKNUJGd3NvN0xXNjdqY3ZSWXEyVW16R1Zlb0hpZ285XC9QbjJ5OUd0NzJUekdCYjNtY2lSaWxrdFNlMDhIYUIrZlhLOHZ2emh4MkV4NXZUSlZcLzhBSStEK0dqWURBQUE9Iiwic3ViIjoibWUiLCJyb2xlcyI6WyJST0xFX0FDVFVBVE9SIiwiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJpc3MiOiJTcHJpbmcgU2VjdXJpdHkgUkVTVCBHcmFpbHMgUGx1Z2luIiwiZXhwIjoxNjI0ODU5NTE3LCJpYXQiOjE2MjQ4NTU5MTd9.1-XT_H9m4XTSUTm55My6aPAmhNr_B2_tQSD-nlSzwao",
  "expires_in" : 3600,
  "refresh_token" : "eyJhbGciOiJIUzI1NiJ9.eyJwcmluY2lwYWwiOiJINHNJQUFBQUFBQUFBSlZTc1c0VFFSUjh2amdLRUJFU0pKQW9Ra1BvMEZtQzBwVmpEQUlkTnJKOVRaQkE2N3VYWTVPOTNjdnVYbUkzeUJVVUtZS0FTRWo4UXY0RUdqNEFRVUdibWc3eDltem5ERTNFVnFmWnVabDViXC9ia0ZCYU5obnVKWmx3WVB4TjV3cVZ2TXMxbFlqREtOYmNqUHplb1k3UUY0MkZCREFtQnlhbDRVQW5BNDdHRnE4RU8yMmMxd1dSUzZ3eDJNTEwxb1lhN1NpZFR4VzNOVWp4UWV0Y1wvMDQ2VXhyOE1TdW5LYncrV3RtQ05SWkhLcFcwcjJScG1YR084QmFzbEZxaG8xMEhYSXJwQmFUa1RacDY2aEpJTkJNWUJMTFBjdmxUa3l0Rll1RElKbTFzdWFqMjA5UUF1Wk13WVN2ZlBKRDNyb3J0N0YxUFNCSHZ3Q3FyRHJFS0hkbmZiVVgybjR6ZVZFRFExVjlKc2hESlZNZFwvbXpwejB4K3Z2dmg1OUdvY2VBTzNrenZuXC9sUGlOVFJoXC9mdjdyWnJIb1NtVGgrbHowa2xZZlpwUm1yVlR1YTNUTzN6NCtmWDk4K3ViWkFqazd4b1BcLzcyT2pNZDNjcUtuU2pHbG0xVnhISkh0UXBlOEZFdDg4WDN6V3dzanY4VFFUU0M5S1dvelBMRXBoR3JlcWxaanQyOExsYmlkb3ZXZzArMkdqMytrYWg2OVl1RFJCN3o5NTFKNUJGd3NvN0xXNjdqY3ZSWXEyVW16R1Zlb0hpZ285XC9QbjJ5OUd0NzJUekdCYjNtY2lSaWxrdFNlMDhIYUIrZlhLOHZ2emh4MkV4NXZUSlZcLzhBSStEK0dqWURBQUE9Iiwic3ViIjoibWUiLCJyb2xlcyI6WyJST0xFX0FDVFVBVE9SIiwiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJpc3MiOiJTcHJpbmcgU2VjdXJpdHkgUkVTVCBHcmFpbHMgUGx1Z2luIiwicmVmcmVzaF9vbmx5Ijp0cnVlLCJpYXQiOjE2MjQ4NTU5MTd9.mKVM7S1Kh_MTn9cRvtEeON45Ub4rdiVR1HssK-IgsA4"
}

Example invalid password response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Date: Mon, 28 Jun 2021 04:51:57 GMT
Keep-Alive: timeout=60
Connection: keep-alive

Error Handling

Here are some examples of how errors are handled

Unauthorized

An example request where not authorization is passed, resulting in a 401 unauthorized error.

Example request

GET /api/user HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: api.restdocs.com
$ curl 'http://api.restdocs.com/api/user' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json; charset=UTF-8'

Example response

HTTP/1.1 401 Unauthorized
Set-Cookie: JSESSIONID=DE4555901B3DF7C4FD677F600F058F06; Path=/; HttpOnly
Transfer-Encoding: chunked
Date: Mon, 28 Jun 2021 04:52:00 GMT
Keep-Alive: timeout=60
Connection: keep-alive
Content-Length: 100

{
  "path" : "/api/user",
  "message" : "This API endpoint requires a valid authentication token."
}

Forbidden

An example request where the url is not valid, resulting in a 403 forbidden error.

Example request

GET /api/user1234/ HTTP/1.1
Authorization: Bearer 12345
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: api.restdocs.com
$ curl 'http://api.restdocs.com/api/user1234/' -i -X GET \
    -H 'Authorization: Bearer 12345' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json; charset=UTF-8'

Example response

HTTP/1.1 403 Forbidden
Transfer-Encoding: chunked
Date: Mon, 28 Jun 2021 04:52:00 GMT
Keep-Alive: timeout=60
Connection: keep-alive
Content-Length: 65

{
  "path" : "/api/user1234/",
  "message" : "Access is denied"
}

Validation

An example request where the body/json is missing required parameters, resulting in a 400 bad request error.

Request Parameters/JSON body

{ }

Request Headers

Name Description

Authorization

Bearer token, from login endpoint.

Accept

This should always be application/json.

Example request

POST /api/user HTTP/1.1
Authorization: Bearer 12345
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: api.restdocs.com
Content-Length: 3

{ }
$ curl 'http://api.restdocs.com/api/user' -i -X POST \
    -H 'Authorization: Bearer 12345' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json; charset=UTF-8' \
    -d '{ }'

Response structure

Path Type Required Description

[].field

String

true

The field that has the roor

[].bindingFailure

Boolean

true

If the error was binding related.

[].rejectedValue

Varies

true

The value for the field that was rejected

[].message

String

true

The error message rendered using i18n mappings.

Example response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Language: en-US
Transfer-Encoding: chunked
Date: Mon, 28 Jun 2021 04:52:00 GMT
Keep-Alive: timeout=60
Connection: keep-alive
Content-Length: 270

[ {
  "field" : "username",
  "bindingFailure" : false,
  "rejectedValue" : null,
  "message" : "Property [username] cannot be null"
}, {
  "field" : "password",
  "bindingFailure" : false,
  "rejectedValue" : null,
  "message" : "Property [password] cannot be null"
} ]

App Version

User