public
Last active

Examples of RESTful API calls for E-commerce platforms

  • Download Gist
e-commerce.md
Markdown

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

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

I suggest you read: http://blog.programmableweb.com/2011/11/18/rest-api-design-putting-the-type-in-content-type/

Have you considered JSON hyper schema? If so, what made you go with HAL?

Interesting article. I chose HAL because it provides a simple standard for hypermedia in JSON. If I was using XML I would have used the atom standard. I also strongly considered Collection+JSON.

I am wary about using schema's for RESTful API's. The web is built on the idea of being liberal with what you accept and strict with what you send.

Hi @hjr3,

This is one of the better examples I've seen for leveraging a hypermedia representation, kudos.

A couple things I'd like to ask about it if you don't mind 10 months later. I'd like to better understand how you are using the link relations in the position of object property name.

Thanks in advance.

Hello @hjr3,

Just like @mikeschinkel, I'm also curious about how you think it's best to handle metadata on "http://example.com/rels/{type}".

Thanks!

Hi @hjr3. Thanks for this. It would be helpful to me, and others I'm sure, if you could add some notes about how you format error responses.

why isn't the payment calculation and order done on a specific cart resource?

Please sign in to comment on this gist.

Something went wrong with that request. Please try again.