API Set Name: products
API Description and Functional Purpose
The products collection contains all product data related to a product catalog. It is a supplemental collection designed specifically to accommodate product data. The most common product related attributes are provided by default as part of the schema.
Related Collections:
The following resource collections are associated to this collection.
Collection | Association |
---|---|
orders | A post to the order method will write to the products collection, where the order items are each added as a specific product variants. |
POST /products
Method | URI Path |
---|---|
POST | /products |
Creates a new product in the Cordial database using the appropriate JSON body.
A product can include one or more variants. Posting the same product more than one time with the same |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
Product | |||
*productID | string | Unique identifier for a product. | AC30 |
*productName | string | The name of the product. | Acme-30 Stapler |
productType | string | The product type. Options include physical, digital, subscription and event. | physical |
price | float | The current price of the product. | 35.99 |
UPCCode | string | The Universal Product Code assigned to the product. | 8 34460 00372 4 |
category | string | The category given to the particular item. | Office Supplies |
images | array | An array of image file locations | http://example.com/images/123 |
manufacturerName | string | The name of the manufacturer. | Acme Supplies |
inStock | boolean | Flags product as in stock. Options are true or false or 1 or 0. The default is false. | 1 |
taxable | boolean | Flags product as taxable. Options are true or false or 1 or 0. The default is false. | 1 |
enabled | boolean | Flags product as enabled. Options are true or false or 1 or 0. The default is false. | 1 |
url | string | A URL to the product page | http://acme.com/ac30 |
tags | array | A comma separated array of values to describe the product | "office","office supplies" |
properties | object | An schema-less object of metadata about a product (as key value pairs). | {"hasVideo": true, "ratings": "5 stars"} |
Variants (array) | |||
*sku | string | The Stock Keeping Unit value for the product. | RF-WP33286-21 |
attr | object | An schema-less object of metadata about a variant (as key value pairs). | {"color": "blue", "size": "medium"} |
qty | integer | The available inventory. | 1 |
Sale (object) | |||
enabled | boolean | Flag to determine if the sale is enabled or active. Options are true or false or 1 or 0. The default is false. | false |
price | float | The item's sale price. | 12.95 |
start | date | The date and time the sale is in effect or active. | 2015-01-09 17:47:43 |
end | date | The date and time the sale ends or goes inactive. | 2015-01-09 17:47:43 |
Example JSON Requests
Simple example (minimum requirements)
{ "productID": "AC30", "productName": "Acme-30 Stapler" }
"Kitchen sink" example (optional fields included)
{ "productID": "AC30", "productName": "Acme-30 Stapler", "variants": [ { "sku": "AC30-1000R", "attr": { "color": "red", "size": "10-inch" }, "qty": 100 }, { "sku": "AC30-1000B", "attr": { "color": "blue", "size": "10-inch" }, "qty": 100 } ], "productType": "physical", "price": 14.95, "sale": { "enabled": true, "price": 12.95, "start": "2016-09-13", "end": "2016-10-13" }, "UPCCode": "8 34460 00372 4", "category": "office_supplies", "images": [ "http://acmeofficesupplies.com/img/ac30-red", "http://acmeofficesupplies.com/img/ac30-blue" ], "manufacturerName": "Acme Office Supplies", "inStock": true, "taxable": true, "enabled": true, "url": "http://acmeofficesupplies.com/AC30", "tags": [ "office", "office supplies", "stapler", "stationary" ], "properties": { "some-key1":"value1", "some-key2":"value2" } }
Example Request URIs
The following URI in conjunction with the JSON will perform the POST.
http://<path>/products
GET /products
Method | URI Path |
---|---|
GET | /products |
Retrieves all products from the Cordial database.
Using query string parameters, it is also possible to filter the field set returned using a query string for the parameter When retrieving a large amount of products in the response, it is possible to apply the |
Parameters
Parameter | Type | Description | Example |
---|---|---|---|
fields | string | Sets which data fields will be returned. | ?fields=productName |
page | number | Page number of results. | ?page=3 |
per_page | number | Number of results per page. | ?per_page=10 |
Example Request URIs
Return all records
The following URI will retrieve all products and include all fields.
http://<path>/products
Return records filtered by a field
The following URI will retrieve all orders, but only include the field data for the productName.
http://<path>/products?fields=productName
Return records filtered by multiple fields
The following URI will retrieve all orders, and include the field data for both productName and category.
http://<path>/products?fields=productName,category
Return records filtered by page number and records per page
The following URI will retrieve all products starting from the third page grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.
http://<path>/products?page=3&per_page=10
GET /products/{id}
Method | URI Path |
---|---|
GET | /products/{id} |
Retrieves a specific product from the Cordial database.
The product is defined by the unique For example, /products/112233 would return the response data for the product with the |
Example Request URIs
The following URI will retrieve the product where the product id is 112233. It will include all fields.
http://<path>/products/112233
PUT /products/{id}
Method | URI Path |
---|---|
PUT | /products/{id} |
Updates a product in the Cordial database using the appropriate JSON body.
The product is defined by the unique For example, /products/112233 would update the the product with the |
Required & Optional Parameters
Same requirements and schema as the POST method above.
Example JSON Requests
The following will update the Acme-30 Stapler, changing the price to 16.95 and marking it as not in stock.
{ "productID": "AC30", "productName": "Acme-30 Stapler", "price": "16.95", "inStock": false }
Example Request URIs
The following URI in conjunction with the JSON will perform the PUT for the product with the productID
of AC30.
http://<path>/products/AC30
DELETE /products/{id}
Method | URI Path |
---|---|
DELETE | /products/{id} |
Deletes a product from the Cordial database.
The product is defined by the products's unique For example, /products/112233 would remove the product with the |
Example Request URIs
The following URI will delete the product where the product id is 112233.
http://<path>/products/112233
Comments
0 comments
Please sign in to leave a comment.