Each REST service endpoint can optionally support up to 5 commands...GET, PUT, POST, DELETE and SEARCH (a use of HTTP POST verb that allows for more complex searching)
Every object be it an order, customer, product or supplier has a unique ID which is a 64 bit unsigned integer can be used when retrieving specific items or assigning them as part of another object when posting. When you retrive any object, its ID is always included in the JSON for you to reference.
The services are accessed using a url format of http://localhost:1034/(ServiceName)
You can use the following syntax to retrieve an item once you know its unique ID... the address will be formatted like this... http://localhost:1034/(ServiceName)/(Unique ID) for example....
http://localhost:1034/Orders/123456987654
...or to use a simple curl statement with an API key of (ABC12MyKey) it might look like...
curl "http://localhost:1034/Orders/123456987654" -H "Authorization : bearer ABC12MyKey"
{
"ID": 9234180100067,
"UpdatedOn": "2013-05-23T14:28:58.467Z",
"CreatedOn": "2009-01-01T14:58:42.91Z",
"Number": "00001",
"Date": "2009-01-03T14:58:12.91",
"Customer": {
"ID": 8594229964136,
"Code": "AC002",
"Name": "Acme Trading Uk Ltd"
},
"Items": [
{
"ID": 9238475067357,
"Product": {
"ID": 21479131853733,
"Code": "OFR2KW",
"Description": "Oil Filled Radiator2KW / 4Kw"
},
"Quantity": 2
},
{
"ID": 9238475067359,
"Product": {
"ID": 21479131853765,
"Code": "MOUSET2",
"Description": "Mouse Trap Cardboard Bait Box"
},
"Quantity": 3
},
{
"ID": 9238475067361,
"Product": {
"ID": 21479131853829,
"Code": "CEMENT",
"Description": "Cement"
},
"Quantity": 2
}
],
"SalesRep": {
"ID": 8602819495830,
"Code": "CN",
"Name": "Chris Norris"
}
}
When you do not specify an id the API will return a collection of items. So the following method will return a collection of orders if a service called orders is enabled...
http://localhost:1034/Orders
...so to use a simple curl statement with an API key of (ABC12MyKey) it might look like...
curl "http://localhost:1034/Orders" -H "Authorization : bearer ABC12MyKey"
Some query string options allow you to filter, sort and paginate the results
The response is a an object containing two properties, TotalCount is the total number of matching items and Data is an array containing the page of items requested.
| Key | Purpose | Sample | Description |
|---|---|---|---|
| fetch | Specify the number of items you want in a page | http://localhost:1034/Orders?fetch=50 |
Returns 50 orders |
| offset | Specify the number of items you want to skip before starting to fetch | http://localhost:1034/Orders?offset=100&fetch=20 |
Returns 20 orders from number 101 to 120 |
| sort | Specify the order in which the items should be sorted | http://localhost:1034/Orders?sort=netamount[dsc],number |
Sorts the orders by netamount in descending order and then by number in ascending order (the default - or [asc]) |
| propertyName[operator]=value | Specify a filter or combination of filters using this notation. The table below has a list of the operators you can use. | http://localhost:1034/Orders?netamount[gte]=150&customer__name[cnt]=Smith |
This gets a list of the orders where the netamount is greater than or equal than 150 and where the customer's name contains 'smith'. You will notice the customer's name is specified as customer__name, this is how properties of nested items are referenced in the query string. Normmally dotted paths are replaced by double underscores. |
| Operator | Description | Applies to... |
|---|---|---|
| eq | Equals | Strings, Numbers, Dates, Booleans |
| neq | Does not equal | Strings, Numbers, Dates, Booleans |
| cnt | Contains | String |
| ncnt | Does not contain | Strings |
| ew | Ends with | Strings |
| sw | Starts with | Strings |
| gt | Greater than | Strings, Numbers, Dates |
| gte | Greater than or equal to | Strings, Numbers, Dates |
| lt | Less than | Strings, Numbers, Dates |
| lte | Less than or equal to | Strings, Numbers, Dates |
{
"TotalCount": 788,
"Data": [
{
"ID": 9234180100067,
"UpdatedOn": "2013-05-23T14:28:58.467Z",
"CreatedOn": "2009-01-01T14:58:42.91Z",
"Number": "00001",
"Date": "2009-01-03T14:58:12.91",
"Customer": {
"ID": 8594229964136,
"Code": "AC002",
"Name": "Acme Trading Uk Ltd Test"
},
"Items": [
{
"ID": 9238475067357,
"Product": {
"ID": 21479131853733,
"Code": "OFR2KW",
"Description": "Oil Filled Radiator2KW / 4Kw"
},
"Quantity": 2
},
{
"ID": 9238475067359,
"Product": {
"ID": 21479131853765,
"Code": "MOUSET2",
"Description": "Mouse Trap Cardboard Bait Box"
},
"Quantity": 3
},
{
"ID": 9238475067361,
"Product": {
"ID": 21479131853829,
"Code": "CEMENT",
"Description": "Cement"
},
"Quantity": 2
}
],
"SalesRep": {
"ID": 8602819495830,
"Code": "CN",
"Name": "Chris Norris"
}
},
{
"ID": 9234180100094,
"UpdatedOn": "2009-01-01T15:01:54.803Z",
"CreatedOn": "2009-01-01T15:01:54.803Z",
"Number": "00003",
"Date": "2009-01-05T15:00:17.273",
"Customer": {
"ID": 8594229964255,
"Code": "RE001",
"Name": "Red Wall Plastering Co"
},
"Items": [
{
"ID": 9238475067384,
"Product": {
"ID": 21479131854021,
"Code": "RECHARGNIK",
"Description": "Battery Recharger Nikon"
},
"Quantity": 3
},
{
"ID": 9238475067386,
"Product": {
"ID": 21479131853877,
"Code": "LEVERCHUB3",
"Description": "Lever Sashlock Brass Chubb 3\""
},
"Quantity": 2
},
{
"ID": 9238475067388,
"Product": {
"ID": 21479131854245,
"Code": "PAINTCEFGRY",
"Description": "Paint Crown Epimac Grey Floor 5L"
},
"Quantity": 5
}
],
"SalesRep": {
"ID": 8602819495830,
"Code": "CN",
"Name": "Chris Norris"
}
}
]
}
You can use a similar address to GET when you need to update an item once you know its unique ID and provided the service supports it ... the address will be formatted like this... http://(API Site Name)/(ServiceName)/(ID) for example....
http://localhost:1034/Orders/123456987654
When doing a PUT you should include a JSON object with the properties and values you want to update in the BODY of the request.
Only properties supporting Write will be accepted and processed by the service.
To see the list of properties supported for each service, visit the documentation for the service
So a simple curl statement to update a Order with ID of 123456987654 might look like this....
curl -X PUT "http://localhost:1034/Orders/123456987654" -H "Authorization : bearer ABC12MyKey" -H "Content-Type: application/json" -d '{ "customer": "AC001", "items": [ { "product" : "HOSE15", "quantity": 10}, { "product" : "CEMENT", "quantity": 5} ] }'
To understand how the request is processed please see the Queue Management section as all items sent to the API are processed in a queue.
{
"description": "New Product Name",
"sellingprice1": 100.00
}
POST works in a similar way to PUT with 2 differencees. Firstly you do not specify an ID in the url ... the address will be formatted like this... http://(API Site Name)/(ServiceName) for example....
http://localhost:1034/Orders
Secondly you can either specify a single JSON object in the body of the message OR an array of objects if you wish to create more than one item.
Only properties supporting Write will be accepted and processed by the service.
To see the list of properties supported for each service, visit the documentation for the service
So a simple curl statement to create 2 new orders might look like this....
curl -X POST "http://localhost:1034/Orders" -H "Authorization : bearer ABC12MyKey" -H "Content-Type: application/json" -d '[ { "customer": "AC001", "items": [ { "product" : "HOSE15", "quantity": 10}, { "product" : "CEMENT", "quantity": 5} ] }, { "customer": "REST90", "items": [ { "product" : "CEMENT", "quantity": 1} ] } ]'
[
{
"customer": "AC001",
"items": [{
"product": "HOSE15",
"quantity": 10
},
{
"product": "CEMENT",
"quantity": 5
}
]
},
{
"customer": "REST90",
"items": [{
"product": "CEMENT",
"quantity": 1
}]
}
]
One thing to notice here is the customer and product objects are specified in the new order using the associated code values e.g. "AC001" or "HOSE15". Its also possible to use the ID of the customers or products, the API will identify the object by its code, ID and finally will attenmpt to match it up using a description where appropriate.
To understand how the request is processed please see the Queue Management section as all items sent to the API are processed in a queue.