Examples of RESTful API calls for E-commerce platforms

These examples are type 3 RESTful API requests and responses. The JSON-HAL specification is used to implement HATEOAS.

Some of the examples are based on my work as architect of the RESTful API at http://www.hautelook.com. All proprietary information has been removed.

Relevant links

JSON-HAL specification: http://stateless.co/hal_specification.html#media_type_identifiers
JSON linking with HAL: http://blog.stateless.co/post/13296666138/json-linking-with-hal
Semantic RESTful documentation: http://geekswithblogs.net/michelotti/archive/2011/06/06/documenting-link-relations-with-web-api.aspx

Examples

Add Item to Cart

A POST request to /member/109087/cart will create a cart resource for the member (if one did not exist) and add the inventory item to the cart. The Location header links to the cart resource that was created or updated. It is optional to add the JSON-HAL representation of that resource as the POST response, but not required.

POST /member/109087/cart HTTP/1.1
Host: api.example.com
Authorization: Basic username:password
Content-type: application/json
Accept: application/hal+json

{
    "inventory_id": 12345,
    "quantity": 1
}

HTTP/1.1 201 Created
Date: Mon, 20 Jun 2011 21:15:00 GMT
Content-Type: application/hal+json
Location: /member/109087/cart/14418796

Get Cart Contents

A GET request to /member/109087/cart will respond with the cart resource and list the contents of the cart items as embedded resources. A link is provided to the payment calculation URI.

GET /member/109087/cart HTTP/1.1
Host: api.example.com
Authorization: Basic username:password
Content-type: application/json
Accept: application/hal+json

HTTP/1.1 200 OK
Date: Mon, 20 Jun 2011 21:15:00 GMT
Content-Type: application/hal+json
Etag: 372b753d68c06990ea22b04b9c9fd4f8

{
   "_links":{
      "self":{
         "href":"/member/109087/cart"
      },
      "http://example.com/rels/payment":{
         "href":"/payment"
      }
   },
   "_embedded":{
      "http://example.com/rels/cart-item":[
         {
            "_links":{
               "self":{
                  "href":"/member/109087/cart/14418796"
               }
            },
            "id":"14418796",
            "quantity":1,
            "expire_time":"2009-09-11T08:00:00-07:00",
            "_embedded":{
               "http://example.com/rels/sku":[
                  {
                     "_links":{
                        "self":{
                           "href":"/skus/654654"
                        },
                        "http://example.com/images/cart/item":"http://example.com/product/6895/thumbnail.jpg"
                     },
                     "color":"Black",
                     "size":"S",
                     "returnable":false,
                     "price":49
                  }
               ]
            }
         }
      ]
   }
}

Calculate Payment

A GET request to /payment will calculate the total amount owed by the member based on the contents in the members cart. The calculation results, along with any discounts (coupons, giftcards, etc) are sent back for the member to review. The relation to http://example.com/payment/coupon allows the member to add and remove any coupons from the calculation.

The choice of shipping and billing addresses to be used during payment are sent back as well. The relations http://example.com/rels/billing and http://example.com/rels/shipping provide allow the member to add, remove and retrieve their billing and shipping addresses. The relations http://example.com/rels/payment/billing and http://example.com/rels/payment/shipping allow the member to apply a different shipping or billing address to the payment calculation.

GET /payment HTTP/1.1
Host: api.example.com
Authorization: Basic username:password
Content-type: application/json
Accept: application/hal+json

HTTP/1.1 200 OK
Date: Mon, 20 Jun 2011 21:15:00 GMT
Content-Type: application/hal+json
Cache-Control: private, no-store

{
   "_links":{
      "self":{
         "href":"/payment"
      },
      "http://example.com/rels/billing":{
         "href":"/member/109087/billing"
      },
      "http://example.com/rels/shipping":{
         "href":"/member/109087/shipping"
      },
      "http://example.com/rels/payment/coupon":{
         "href":"/payment/coupon"
      },
      "http://example.com/rels/payment/billing":{
         "href":"/payment/billing"
      },
      "http://example.com/rels/payment/shipping":{
         "href":"/payment/shipping"
      },
      "subtotal":49,
      "tax":0,
      "freight":5,
      "total":44,
      "_embedded":{
         "http://www.example.com/rels/coupon":[
            {
               "type":"dollarOff",
               "amount":"10",
               "code":"A0318A97"
            }
         ],
         "http://example.com/rels/shipping":{
            "_links":{ 
               "self":{
                  "href":"/shipping/135451" 
               } 
            },
            "first_name":"Heman",
            "last_name":"Radtke",
            "address":"1234 Day St.",
            "city":"Los Angeles",
            "state":"CA",
            "zipcode":"90015",
            "country_iso":"US"
         },
         "http://example.com/rels/billing":{
            "_links":{ 
               "self":{
                  "href": "/billing/135451" 
               } 
            },
            "first_name":"Herman",
            "last_name":"Radtke",
            "address":"1234 Day St.",
            "city":"Los Angeles",
            "state":"CA",
            "zipcode":"90015",
            "country_iso":"US",
            "card_number":"1111",
            "card_type":"mastercard",
            "card_exp_year":"2015",
            "card_exp_month":"01"
         }
      }
   }
}

Place Order

A POST request to /orders will create an order resource based on the contents of the members cart.

POST /orders HTTP/1.1
Host: api.example.com
Authorization: Basic username:password
Content-type: application/json
Accept: application/hal+json

HTTP/1.1 201 Created
Date: Mon, 20 Jun 2011 21:15:00 GMT
Content-Type: application/hal+json
Location: /orders/453435

divyanshu-in/e-commerce.md