Order Shorthand
/order
A shorthand that allows a user to access directly the current open order with the appropriate OwnerId.
Request Headers
- Cookie
- Required. Any call trying to use the shorthand notation has to have a valid OwnerId cookie set, with the exception of calls that will create a new order implicitly. A valid Set-Cookie header is returned with the response of either implicit or explicit order creation calls.
Order Shorthand
Using /order will try to find an order with status new that is associated with the OwnerId specified in the cookie header sent with the request. The value of the cookie may be set by either explicit or implicit order creation.
Available Methods and Child Resources
The shorthand supports all the methods that are available when using the /orders/{orderId} notation and all of the order's child resources are also accessible using the shorthand. A GET call to the order shorthand itself will include an alternate link to the explicit URL of the order in the hypermedia section. If an order is submitted using the shorthand URL, a Location header containing the explicit location of the order will be returned with a successful response for future reference.
Implicit Order Creation
If there is no current order associated with the active user, that is not submitted, a PUT or POST call to a child resource will implicitly create a new order for the user and will populate the data of the actual call to the new order. The final response of the implicitly created order will contain additional Set-Cookie header as described below. A GET or OPTIONS call to a non-existing order will not create it implicitly, but will return response with 404 status code.
Response Headers
- Set-Cookie
- If an order is created implicitly while accessing a child resource, the final response will include a Set-Cookie header containing an OwnerId identifier, in a similar way to explicit creation of an order using POST /orders. The cookie will be used to identify the end user, if no existing account is associated with the order, and to find which is the currently open order associated with the end client.
Additional Status Code
In addition to the response status codes that can be returned by various /orders/{orderId} calls, the order shorthand may also return:
- 409 Conflict
- There is already a new order associated with the same OwnerId and a second order cannot be created until the existing one is either submitted or deleted.
OwnerId cookie
Definition and purpose
The Order API defines the so called order shorthand. The Order shorthand is exposing all Order API resources and subresources, without supplying the order id. This means that at given time only one order instance is available to a client session. The Order API identifies the order instance by using "OwnerId" cookie.
Order states and OwnerId cookie life cycle
Fresh client session
When client with fresh session starts using the Order API through the shorthand the order API is designed to create order instance implicitly. The created order instance is in "new" state. When the order instance is created, the Order API will return a Set-Cookie HTTP header for setting the "OwnerId" cookie into the client session.
Subsequent calls to order shorthand resources/subresources
Once the OwnerId has been set to the client session, the client should start providing the OwnerId cookie in all subsequent calls to Order API. Receiving request with OwnerId cookie will make Order API search for oder instance in "new" state, identified by the OwnerId
Order instance deletion or submission
From "new" state the order instance can be deleted or submitted for provisioning. If the order is submitted its state will be changed to "placed".
Refreshing the OwnerId cookie after the order gets deleted or submitted
Subsequent calls, which identifies deleted or "placed" order instance will trigger Order API to implicitly create a new order instance and respond with Set-Cookie HTTP header with e new OwnerId value. The client session should start using the new OwnerId value when calling the Order API.
CORS (Cross-origin resource sharing) and OwnerId cookie
All browser based clients should abide the security policies enforced by the browsers itself. One such policy is the same origin security policy. To overcome the same origin security policy the browsers are providing the so called CORS (Cross-origin resource sharing) mechanism - http://en.wikipedia.org/wiki/Cross-origin_resource_sharing.
Basically the CORS mechanism makes the browsers to "disallow" requests which are originating from domain that does not match one of the Access-Control-Allow-Origin response header values. Ideally the Public API should allow calls, originated from all domains, by setting the Access-Control-Allow-Origin response header to * (Asterisk). Unfortunately when the requests are containing cookies the CORS mechanism dictates that the Access-Control-Allow-Origin should be very specific to the allowed domains(https://developer.mozilla.org/en-US/docs/HTTP/Access_control_CORS?redirectlocale=en-US&redirectslug=HTTP_access_control#Requests_with_credentials), meaning that your domain should be set into the Public API allowed domains. If your domain is not set to the Public API allowed domains, then please contact your sales or technical person and ask them to do that for you.
Examples
Implicit Creation
Request
PUT /order/account
Content-Type: application/json; charset=UTF-8
Authorization: {Base64-encoded username & password string}
{
"currency": "USD",
"language": "en-US"
}
Response
200 OK Set-Cookie: OwnerId=4d84cd13-bbb3-46ba-a40c-8988351e3681; Path=/order Set-Cookie: OwnerId=4d84cd13-bbb3-46ba-a40c-8988351e3681; Path=/orders
Alternate Hypermedia
Request
GET /order
Authorization: {Base64-encoded username & password string}
Cookie: OwnerId=4d84cd13-bbb3-46ba-a40c-8988351e3681; Path=/order
Response
200 OK
Content-Type: application/json; charset=UTF-8
{
"order": {
"OwnerId": "4d84cd13-bbb3-46ba-a40c-8988351e3681"
},
"links": {
"self": {"href": "https://api.hostway.com/order/", "rel": "self"},
"alternate": {"href": "https://api.hostway.com/orders/{orderId}/", "rel": "alternate"}
}
}
Accessing a Child Resource
Request
GET /order/product/{productId}
Authorization: {Base64-encoded username & password string}
Cookie: OwnerId=4d84cd13-bbb3-46ba-a40c-8988351e3681; Path=/order
Response
200 OK
Content-Type: application/json; charset=UTF-8
{
"status": "new",
"services": "https://api.hostway.com/order/product/{productId}/services",
"offering": "https://api.hostway.com/productSpecifications/{productSpecId}/offerings/{offering}",
"links": [
{"href": "https://api.hostway.com/order/product/{productId}/", "rel": "self"}
]
}
See also
