OCAPI HTTP Methods

A key characteristic of a RESTful Web API is the explicit use of HTTP methods, as defined by RFC 2616. The Open Commerce API supports these methods, as described in the following sections.

The GET method retrieves resources on the server. The GET method is a safe method, which means that it should never change the state of the server or have side effects. Consequently, a GET request never initiates transactions on the server.

A typical GET request and its response look like this:

1REQUEST:
2GET /dw/shop/v24_5/products/123 HTTP/1.1
3Host: example.com
4Accept: application/json
5
6RESPONSE:
7HTTP/1.1 200 OK
8Content-Length: 67
9Content-Type: application/json; charset=UTF-8
10
11{"sku":"123","name":"foo","brand":"bar","online":true}

This sample shows a typical GET request retrieving a Product resource using the Identifier “123”. The response has HTTP status code 200, which indicates the resource was found and is contained in response body. The response contains the “Content-Type” header, which is set to “application/json” plus the charset definition (“UTF-8”).

The DELETE method removes one or more resources on the server. DELETE is an idempotent method, which means repeating a request always results in the same server state as making the request once. The server returns HTTP status code 204 (NO CONTENT) if the resource has been deleted or 404 (NOT FOUND) if the resource doesn’t exist (anymore).

The following example shows how to remove a resource that is addressed by an Identifier in the URL:

1REQUEST:
2DELETE /dw/shop/v24_5/baskets/12345abcdfe12345 HTTP/1.1
3Host: example.com
4Accept: application/json
5
6RESPONSE:
7HTTP/1.1 204 NO CONTENT
8Content-Length: 0

The request is similar to the previous GET request, except the HTTP method changed. The response status code is 204, which means the server successfully fulfilled the request but returned no content.

The PUT method is used to create, update, or replace a resource. It’s also an idempotent method. If a resource is created, the method returns a 201 status code with a Location header, pointing to the created resource. Otherwise, it returns a 200 status code.

PUT allows you to create a resource with the identifier specified in the URL. POST, on the other hand, is used when the identifier is provided by the server.

If the resource exists, PUT “cleans” the resource and then applies all the properties specified in the request document. So, unlike PATCH, PUT also touches/cleans properties that aren’t part of the request document. The PUT replace logic touches only the resource itself, not its relations to other resources.

The example shows how to set a billing address on a basket using the PUT method:

1REQUEST:
2PUT /dw/shop/v24_5/baskets/cdTwMiWbOhGJgaaadkIKbj5op9/billing_address HTTP/1.1
3Host: example.com
4Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
5Content-Type: application/json
6{
7  "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
8  "first_name":"John",
9  "last_name":"Smith",
10  "city":"Boston",
11  "country_code":"US",
12  "c_strValue":"c25"
13}
14
15RESPONSE:
16HTTP/1.1 200 OK
17Content-Type: application/json;charset=UTF-8
18
19{
20   "_v" : "24.5",
21   "_resource_state" : "t9ccde3040519cce439cd99e209f8a87c3ad0b7e2"
22...
23   "billing_address" :
24   {
25      "_type" : "order_address",
26      "city" : "Boston",
27      "country_code" : "US",
28      "first_name" : "John",
29      "full_name" : "John Smith",
30      "last_name" : "Smith",
31      "c_strValue" : "c25"
32   },
33...
34}

The PATCH method allows partial resource modification by sending a delta document. The method is neither safe nor idempotent. A PATCH document contains information describing how to modify a server resource to produce a new version; in contrast, a PUT request completely replaces the existing document.

The Open Commerce API uses the PATCH method to provide partial updates. The following table compares PUT and PATCH regarding their create and update behavior:

The example shows how you can use a PATCH to partially update a baskets resource. The server updates only the properties in the delta document; other properties are untouched:

1REQUEST:
2#
3# Example: Update Option Value
4#
5REQUEST:
6PATCH /dw/shop/v24_5/baskets/cd6HwiWbLaZuUaaadgtglhMTrG/items/cdheYiWbLasNkaaadgwMthMTrG HTTP/1.1
7Host: example.com
8Authorization: Bearer a5b6eb0dxxxxxx.423f234ff24fxxxxx.124f1f133fxxxxx
9
10{
11  "_resource_state" : "t9ccde3040519cce439cd99e209f8a87c3ad0b7e2"
12  "product_id": "IPad2",
13  "quantity": 1,
14  "option_items": [
15    {
16      "option_id": "Warranty",
17      "option_value_id": "oneYear"
18    }
19  ]
20}
21
22# Success Response:
23RESPONSE:
24HTTP/1.1 200 OK
25Content-Type: application/json;charset=UTF-8
26Cache-Control: max-age=0,no-cache,no-store,must-revalidate
27{
28   "_v" : "24.5",
29   "_resource_state" : "125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f19.10ff0ba0fc46de88"
30...
31   "basket_id" : "cd6HwiWbLaZuUaaadgtglhMTrG",
32   "product_items" : [
33      {
34...
35         "item_text" : "IPad 2",
36         "option_items" : [
37            {
38               "item_text" : "Warranty One Year",
39               "option_id" : "Warranty",
40               "option_value_id" : "oneYear",
41...
42            }
43         ],
44         "product_id" : "IPad2",
45         "item_id" : "cdheYiWbLasNkaaadgwMthMTrG"
46      }
47   ],
48   ...
49}

The POST method is neither safe (because requests can affect the server state) nor idempotent (because multiple requests potentially return different results).

The Open Commerce API uses POST only for three purposes:

• Create a resource. Unlike PUT, the resource identifier is provided by the server.
• Override an HTTP method; see Override HTTP method.
• Execute special actions that are hard to map to a RESTful request (for example, password reset requests).

The HEAD method is similar to the GET method, but returns headers only, not content (body). The headers are identical to those of the GET request. The HEAD method is a safe method: it doesn’t change the state of the server.

1REQUEST:
2HEAD /dw/shop/v24_5/products/123 HTTP/1.1
3Host: example.com
4Accept: application/json
5
6RESPONSE:
7HTTP/1.1 204 NO CONTENT
8Content-Length: 67
9Content-Type: application/json; charset=UTF-8

The OPTIONS method lists the supported HTTP methods for the specified URL in the Allow header. It isn’t cache-able and returns no content. The OPTIONS method is also a safe method, which means that it will never change the state of the server.

1REQUEST:
2OPTIONS /dw/shop/v24_5/products HTTP/1.1
3Host: http://example.com
4
5RESPONSE:
6HTTP/1.1 204 NO CONTENT
7Allow: GET, HEAD, POST

Some web frameworks (for example, AJAX frameworks) only support the HTTP methods GET and POST. The Open Commerce API works around this limitation by supporting POST requests that can override the HTTP method. The methods DELETE, HEAD, OPTIONS, PUT and PATCH are supported override methods.

You can do this by specifying the explicit request/form parameter method with the value of the overriding method in upper case. The following example shows how you can simulate a DELETE:

1REQUEST:
2POST /dw/shop/v24_5/products/123?method=DELETE HTTP/1.1
3Host: example.com
4Accept: application/json
5
6RESPONSE:
7HTTP/1.1 204 NO CONTENT

Another way you can override the HTTP method is to specify the B2C Commerce Digital HTTP header x-dw-http-method-override with the value of the overriding method in upper case. The following example shows how you can simulate a DELETE:

1REQUEST:
2POST /dw/shop/v24_5/products/123 HTTP/1.1
3Host: example.com
4Accept: application/json
5x-dw-http-method-override: DELETE
6
7RESPONSE:
8HTTP/1.1 204 NO CONTENT

Some of the PATCH, POST, and PUT OCAPIs might not require a request body. Making these calls with empty request bodies can cause problems (i.e. HTTP 500 responses) with proxies in between. Please ensure that you provide the Content-Length request header with the value ‘0’.

1REQUEST:
2POST /dw/shop/v24_5/sessions HTTP/1.1
3Host: example.com
4Content-Length: 0