Revision as of 07:59, 9 September 2014

/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:

Status Code

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

• Orders API
• Common Features