...
{numberedHeadings}
h1. Contents
{toc}
h2. Introduction
The Crafter Commerce API is meant to provide access to all major functionality using RESTful web service calls. The API will be implemented for both XML and JSON input and output, to stay as technology-agnostic as possible. Every service call will represent an atomic operation on the underlying system. In-flight data will be persisted to a backend data store so that it can be retrieved and manipulated in future user sessions. All REST API calls are divided over a couple of logical services, each providing CRUD type operations, as well as more specialized business-logic related operations.
h2. Object Types
The Crafter Commerce domain model is fairly simple, with known entities represented as POJOs that can have references to other POJOs. A POJO can be expresses an XML or JSON output by the API.
h3. Product
A product is a physical good, an electronic good, or service offering. The Product is at the heart of every Crafter Commerce transaction and is often where the transaction starts.
h3. Profile
The Profile type refers to user profiles, which contain user information necessary for a Crafter Commerce transation.
{code:title=XML}
<profile>
<id>spaceduck</id>
<orders>
<order><id>394013</id></order>
<order><id>401232</id></order>
</orders>
<addresses>
<address>
</address>
</addresses>
<shopping-cart>
</shopping-cart>
</profile>
{code}
{code:title=JSON}
{
"profile": {
"id": "spaceduck",
"orders": {
"order": [
{"id": "394013"},
{"id": "401232")
]
}
}
}
{code}
h3. Address
TBD
{code:title=XML}
TBD
{code}
{code:title=JSON}
{
"address": {}
}
{code}
h3. PricePlan
A PricePlan is a product's price in a specific scope, such as a location or point in time. PricePlans can be defined for different currencies and locations.
{code:title=XML}
<price-plan>
<id>8392013</id>
<name>Product X Canada Price Plan</name>
<product>3910-22203</product>
<amount>29.99</amount>
<currency>CAD</currency>
<location>Canada</location>
<latitude>...</latitude>
<longitude>...</longitude>
<start-date>...</start-date>
<end-date>...</end-date>
<promotions>
<promotion>394023</promotion>
<promotion>394024</promotion>
<promotion>394026</promotion>
</promotion>
<terms-conditions>
<![CDATA[ All the good stuff here ]]>
</terms-conditions>
</price-plan>
{code}
{code:title=JSON}
{
"price-plan": {
"id": "8392013",
"name": "Product X Canada Price Plan",
"product": {"id": "3910-22203"},
"amount": "29.99",
"currency": "CAD",
"location": "Canada",
"start-date": "...",
"end-date": "...",
"promotions": {
"promotion": [
{"id": "394023"},
{"id": "394024"},
{"id": "394026"}
]
},
"terms-and-conditions": "All the good stuff here"
}
}
{code}
h3. Promotion
TBD
{code:title=XML}
TBD
{code}
{code:title=JSON}
TBD
{code}
h3. Order
The Order represents an actual Crafter Commerce transaction, where a payment is made and delivery is confirmed to the customer.
{code:title=XML}
<order>
<id>123>/id>
<customer>spaceduck</customer>
<products>
<product>
<id>3729</id>
<name>Power Glue</name>
<price>19.99</price>
</product>
</products>
<payment>...</payment>
<instructions>Special instructions</instructions>
<order-date>2004-02-12T15:19:21</order-date>
<shipping-date>...</shipping-date>
<delivery-date>...</shipping-date>
<status>COMPLETED</status>
</order>
{code}
h3. Payment
TBD
{code:title=XML}
TBD
{code}
{code:title=JSON}
TBD
{code}
h2. Services
h3. Product Service
h4. Create Product
*Resource URL*
{code}
POST /api/1/product/create.{format}
{code}
*Parameters*
|| Parameter || Required? || Multi-valued? || Description ||
| name | y | | The product's name |
| brand | | | The product's brand |
| sku | | y | The product's Stock Keeping Unit |
| parent-id | | | The ID of the product's parent product |
| child-id | | y | The ID of the product's child product |
| price-plan-id | | y | The ID of the product's price plan |
*Response*
{code:title=XML Response}
<product>
<id>738103-321</id>
<name>Widget Bugs Turbo Diesel</name>
<brand>Lucky Brand</brand>
<skus>
<sku>DEQ-439032.123</sku>
<sku>102-312-311</sku>
</skus>
<parent>
<product><id>300132-342</id></product>
<children>
<product><id>103321-532</id></product>
<product><id>332121-442</id></product>
</children>
<price-plans>
<price-plan><id>133422</id></price-plan>
<price-plan><id>134322</id></price-plan>
</price-plans>
</product>
{code}
{code:title=JSON Response}
{
"product": {
"id": "738103-321",
"name": "Widget Bugs Turbo Diesel",
"brand": "Lucky Brand",
"skus": [
{"sku": "DEQ-439032.123"},
{"sku": "102-312-311"}
],
"parent": {
"product": {
"id": "300132-342"
}
},
"children": {
"product": [
{"id": "103321-532"},
{"id": "332121-442"}
]
},
"price-plans": {
"price-plan": [
{"id": "133422"},
{"id": "134322"}
]
}
}
}
{code}
h4. Update Product
*Resource URL*
{code}
POST /api/1/product/{id}/update.{format}
{code}
*Parameters*
|| Parameter || Required? || Multi-valued? || Description ||
| name | y | | The product's name |
| brand | | | The product's brand |
| sku | | y | The product's Stock Keeping Unit |
| parent-id | | | The ID of the product's parent product |
| child-id | | y | The ID of the product's child product |
| price-plan-id | | y | The ID of the product's price plan |
*Response*
h4. Get Products
{code}
GET /api/1/product/all.{format}
GET /api/1/product/id/{id}
GET /api/1/product/type/{type-id}
{code}
h4. Delete Product