Overview
HTTP verbs
Our application tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.
| Verb | Usage |
|---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource, including partial updates |
|
Used to delete an existing resource |
HTTP status codes
Our application tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.
| Status code | Usage |
|---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been accepted, and will be processed asynchronously. For example an event was accepted by the state machine |
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
An update to an existing resource has been rejected for semantic reasons. For example an event has not been processed by the state machine. |
|
The requested resource did not exist |
Headers
Every response has the following header(s):
| Name | Description |
|---|---|
|
The Content-Type of the payload, e.g. |
Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:
| Path | Type | Description |
|---|---|---|
|
|
The HTTP error that occurred, e.g. |
|
|
A description of the cause of the error |
|
|
The path to which the request was made |
|
|
The HTTP status code, e.g. |
|
|
The time, in milliseconds, at which the error occurred |
For example, a request that attempts to create an order with invalid JSON will produce a
400 Bad Request response:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 163
{
"timestamp" : "2018-09-18T16:27:48.889+0000",
"status" : 400,
"error" : "Bad Request",
"message" : "The order cannot be created.",
"path" : "/orders"
}Hypermedia
Our application uses hypermedia and resources include links to other resources in their
responses. Responses are in Hypertext Application
Language (HAL) format. Links can be found beneath the _links key. Users of the API should
not create URIs themselves, instead they should use the above-described links to navigate
from resource to resource.
Resources
Index
The index provides the entry point into the service.
Accessing the index
A GET request is used to access the index
Response structure
| Path | Type | Description |
|---|---|---|
|
|
Links to other resources |
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 206
{
"_links" : {
"orders" : {
"href" : "http://localhost:8080/orders{?page,size,sort}",
"templated" : true
},
"profile" : {
"href" : "http://localhost:8080/profile"
}
}
}Links
| Relation | Description |
|---|---|
|
The Orders resource |
|
The ALPS profile for the service |
Orders
The Orders resource is used to create and list orders.
Listing orders
A GET request will list all orders.
Response structure
| Path | Type | Description |
|---|---|---|
|
|
Embedded list of Order resources |
|
|
paging information |
Example request
$ curl 'http://localhost:57214/orders' -i -X GETExample response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 18 Sep 2018 16:27:54 GMT
Content-Length: 1452
{
"_embedded" : {
"orders" : [ {
"currentState" : "Canceled",
"_links" : {
"self" : {
"href" : "http://localhost:57214/orders/2"
},
"order" : {
"href" : "http://localhost:57214/orders/2"
},
"reopen" : {
"href" : "http://localhost:57214/orders/2/receive/Reopen"
},
"receive-payment" : {
"href" : "http://localhost:57214/orders/2/receive/ReceivePayment"
}
}
}, {
"currentState" : "Open",
"_links" : {
"self" : {
"href" : "http://localhost:57214/orders/3"
},
"order" : {
"href" : "http://localhost:57214/orders/3"
},
"receive-payment" : {
"href" : "http://localhost:57214/orders/3/receive/ReceivePayment"
},
"cancel" : {
"href" : "http://localhost:57214/orders/3/receive/Cancel"
},
"unlock-delivery" : {
"href" : "http://localhost:57214/orders/3/receive/UnlockDelivery"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "http://localhost:57214/orders{?page,size,sort}",
"templated" : true
},
"profile" : {
"href" : "http://localhost:57214/profile/orders"
},
"search" : {
"href" : "http://localhost:57214/orders/search"
}
},
"page" : {
"size" : 20,
"totalElements" : 2,
"totalPages" : 1,
"number" : 0
}
}Creating an order
A POST request is used to create an order
Request structure
| Path | Type | Description |
|---|
Example request
$ curl 'http://localhost:57214/orders' -i -X POST \
-H 'Accept: application/hal+json' \
-H 'Content-Type: application/json; charset=UTF-8' \
-d '{}'Example response
HTTP/1.1 201 Created
Location: http://localhost:57214/orders/3
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 18 Sep 2018 16:27:53 GMT
Content-Length: 489
{
"currentState" : "Open",
"_links" : {
"self" : {
"href" : "http://localhost:57214/orders/3"
},
"order" : {
"href" : "http://localhost:57214/orders/3"
},
"receive-payment" : {
"href" : "http://localhost:57214/orders/3/receive/ReceivePayment"
},
"cancel" : {
"href" : "http://localhost:57214/orders/3/receive/Cancel"
},
"unlock-delivery" : {
"href" : "http://localhost:57214/orders/3/receive/UnlockDelivery"
}
}
}Order
The Order resource is used to navigate to sub-resources triggering order change events.
Links
| Relation | Description |
|---|---|
|
POST: Unlock delivery, to enable fulfillment process even if payment has not been received yet. |
|
POST: Deliver products |
|
POST: Receive Payment |
|
POST:T Start refund process |
|
POST: Reopen a closed order |
|
POST: Cancel an order |
Retrieve an order
A GET request will retrieve the details of an order
Response structure
| Path | Type | Description |
|---|---|---|
|
|
Current order state. Localized and meant for display purposes only |
Example request
$ curl 'http://localhost:57214/orders/2' -i -X GET \
-H 'Accept: application/hal+json'Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 18 Sep 2018 16:27:53 GMT
Content-Length: 489
{
"currentState" : "Open",
"_links" : {
"self" : {
"href" : "http://localhost:57214/orders/2"
},
"order" : {
"href" : "http://localhost:57214/orders/2"
},
"receive-payment" : {
"href" : "http://localhost:57214/orders/2/receive/ReceivePayment"
},
"cancel" : {
"href" : "http://localhost:57214/orders/2/receive/Cancel"
},
"unlock-delivery" : {
"href" : "http://localhost:57214/orders/2/receive/UnlockDelivery"
}
}
}Triggering order change events
A POST request to one of the order event sub-resources will trigger a change event for an order.
The order resource will only expose links to event sub-resources that are expected to be valid, and
the state machine will only process certain events in certain states (see statemachine diagram).
Response structure
The response code will be either be 202 Accepted or 422 Unprocessable Entity, while the response body will always
be empty.
Example request
$ curl 'http://localhost:57214/orders/2/receive/ReceivePayment' -i -X POST \
-H 'Accept: application/hal+json' \
-H 'Content-Type: application/json; charset=UTF-8'Example response
HTTP/1.1 202 Accepted
Date: Tue, 18 Sep 2018 16:27:53 GMT