Simple API design for store

README.md

Simple API design for store

Simple API design for WebGroup.

Data model

Store has categories and products beloned to. Each product may has several tags.

Response formats

All api calls returns data as JSON or XML. You must set Accept header to determine response format, eg Accept: application/json. If unsupported format given, server returns 406 Not acceptable.

Authentication

Authentication is not needed.

Documentation syntax

API calls represnted as VERB /api/path, where VERB - HTTP verb and /api/path - API path.

Wrong params

If given parameter is wrong server returns 400 Bad request:

{"error": "Unknown parameter given: foo"}

If parameter given is correct but given wrong value server returns 422 Unprocessable entity:

{"error": "The tags parameters accepts the array of strings"}

Usage

Category list

API call

GET /api/v1/categories

Response

Returns an Array of categories

Example response

[
    {"id": 1, "name": "Desktops"},
    {"id": 2, "name": "Laptops"},
    {"id": 3, "name": "Printers, scanners and MFD"},
    {"id": 4, "name": "Mobile phones"}
]

Category details

API call

GET /api/v1/categories/:category_id

Parameters

• :category_id - the ID of given category, eg: 1

Response

Returns details of category as a Object with 200 OK if exists or 404 Not Found header otherwise, eg:

{"error": "Category not found"}

Category exists

HEAD /api/v1/categories/:category_id

Returns header 200 OK if exists or 404 Not Found header otherwise.

List products

List of products belonged to category with ID :category_id

API call

GET /api/v1/categories/:category_id/products

Parameters

• :category_id - the ID of given category, eg: 1

Response

Returns an Array of products.

Example response

[
	{
		"id": 1,
		"category_id": 2,
		"name": "Apple MacBook Pro 13\" with Retina display 2014 (MGX72)",
		"price": 1500.0,
		"currency": "USD",
		"tags": ["apple", "macbook", "macbook pro", "laptop", "os x"]
	},
	{
		"id": 2,
		"category_id": 2,
		"name": "Apple MacBook Air 13\" (MD760) (2014)",
		"price": 1100.0,
		"currency": "USD",
		"tags": ["apple", "macbook", "macbook air", "laptop", "os x"]
	},
	{
		"id": 3,
		"category_id": 2,
		"name": "ASUS Transformer Book T100TA (T100TA-DK003H)",
		"price": 400.0,
		"currency": "USD",
		"tags": ["asus", "transformer book", "laptop", "windows"]
	},
	{
		"id": 4,
		"category_id": 4,
		"name": "Apple iPhone 6 64GB (Space Gray)",
		"price": 850.0,
		"currency": "USD",
		"tags": ["apple", "iphone", "iphone 6", "smartphone", "space gray", "ios"]
	},
	{
		"id": 5,
		"category_id": 4,
		"name": "HTC One 801e (Silver)",
		"price": 440.0,
		"currency": "USD",
		"tags": ["htc", "htc one", "silver", "smartphone", "android"]
	}
]

List of products filtered by tags

Returns an Array of products.

API call

GET /api/v1/categories/:category_id/products

Parameters

• :category_id - the ID of given category, eg: 1
• tags[] - list of tags, eg: tags[]=apple&tags[]=macbook
• operator (optional) - logical operator, may be AND (default), OR.

Example Response

GET /api/v1/categories/:category_id/products?tags[]=apple&tags[]=laptop&operator=AND

[
	{
		"id": 1,
		"category_id": 2,
		"name": "Apple MacBook Pro 13\" with Retina display 2014 (MGX72)",
		"price": 1500.0,
		"currency": "USD",
		"tags": ["apple", "macbook", "macbook pro", "laptop", "os x"]
	},
	{
		"id": 2,
		"category_id": 2,
		"name": "Apple MacBook Air 13\" (MD760) (2014)",
		"price": 1100.0,
		"currency": "USD",
		"tags": ["apple", "macbook", "macbook air", "laptop", "os x"]
	}
]

Product details

API call

GET /api/v1/categories/:category_id/products/:product_id

Parameters

• :category_id - the ID of given category, eg: 1
• :product_id - the ID of given product, eg: 1

Response

Returns details of category as a Object with 200 OK if exists or 404 Not Found header otherwise, eg:

{"error": "Product not found"}

Example response

GET /api/v1/categories/4/products/4

{
	"id": 4,
	"category_id": 4,
	"name": "Apple iPhone 6 64GB (Space Gray)",
	"price": 850.0,
	"currency": "USD",
	"tags": ["apple", "iphone", "iphone 6", "smartphone", "space gray", "ios"]
}