1. Contents
1.1. 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.
1.2. 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.
1.2.1. 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.
1.2.2. Profile
The Profile type refers to user profiles, which contain user information necessary for a Crafter Commerce transation.
<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>
{
"profile": {
"id": "spaceduck",
"orders": {
"order": [
{"id": "394013"},
{"id": "401232")
]
}
}
}
1.2.3. Address
TBD
TBD
{
"address": {}
}
1.2.4. 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.
<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>
{
"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"
}
}
1.2.5. Promotion
TBD
TBD
TBD
1.2.6. Order
The Order represents an actual Crafter Commerce transaction, where a payment is made and delivery is confirmed to the customer.
<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>
1.2.7. Payment
TBD
TBD
TBD
1.3. Services
1.3.1. Product Service
1.3.1.1. Create Product
Resource URL
POST /api/1/product/create.{format}
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
<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>
{
"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"}
]
}
}
}
1.3.1.2. Update Product
Resource URL
POST /api/1/product/{id}/update.{format}
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
1.3.1.3. Get Products
GET /api/1/product/all.{format}
GET /api/1/product/id/{id}
GET /api/1/product/type/{type-id}
1.3.1.4. Delete Product
POST /api/1/product/id/{id}/delete
1.3.2. Profile Service
NEED TO USE CRAFTER PROFILE FOR THIS
1.3.2.1. Create Pofile
POST /api/1/profile/create
1.3.2.2. Update Profile
POST /api/1/profile/update
1.3.2.3. Find Profile
GET /api/1/profile/find/${query}
1.3.2.4. Delete Profile
POST /api/1/profile/delete/${profile-id}
1.3.3. Order Service
1.3.3.1. Create Order
POST /api/1/order/create/${user}
TBD
1.3.3.2. Find Order
GET /api/1/order/find/
1.3.3.3. Update Order
1.3.3.4. Delete Order
1.3.4. Transaction Service
1.3.5. Utility Services
1.3.5.1. Address Validator Service
TBD
1.3.5.2. Shipping Cost Service
TBD
1.3.5.3. Tax Calculation Service
TBD