(Quick Reference)
20 Items - Reference Documentation
Version: 2.1
20 Items
20.1 List
Service: List items Description: This web service returns a json list of items. URL: https://BASE_URL/api/VERSION/items : GET Parameters: Pagination parameters: | Name | Description | Type | Required | Possible values |
|---|
| max | Limits the number of resources requested to return. | Integer | no | | | offset | Tells where to start returning records from the entire set of results. | Integer | no | | | order | Orders ascending or descending. | Integer | no | asc,desc | | sort | Orders the results by the specified field. | String | no | |
The max parameter is set to 100 by default. Filters parameters:
| Name | Description | Type | Required | Example values |
|---|
| dateCreated_gt | Filters by the resource's creation date time and operator greater than | Date | no | 2016-08-15T14:52:48Z | | dateCreated_gte | Filters by the resource's creation date time and operator greater than or equal | Date | no | | | dateCreated_lt | Filters by the resource's creation date time and operator less than | Date | no | | | dateCreated_lte | Filters by the resource's creation date time and operator less than or equal | Date | no | | | lastUpdated_gt | Filters by the resource's last-modified date time and operator greater than | Date | no | | | lastUpdated_gte | Filters by the resource's last-modified date time and operator greater than or equal | Date | no | | | lastUpdated_lt | Filters by the resource's last-modified date time and operator less than | Date | no | | | lastUpdated_lte | Filters by the resource's last-modified date time and operator less than or equal | Date | no | | | reference | Wildcard search by the resource's reference | String | no | reference=Ref-6* , reference=*ef-6 , reference=*ef-6* | | name | Wildcard search by the resource's name | String | no | |
Dates should be formatted as the ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ)
Success OutputStatus: HTTP/1.1 200 OK {
"paging": {
"total": 526,
"max": 5,
"offset": 0,
"previous": null,
"next": "/api/v1.0/items?max=5&order=asc&offset=5&sort=dateCreated"
},
"data": [
{
"id": 519,
"reference": "bracelet-GRP09062",
"name": "Knot Band Bracelet",
"description": "",
"itemCategoryId": 2,
"itemCategory": {
"id": 2,
"reference": "Ref-01",
"name": "Jewelry",
"href": "/api/v1.0/itemCategories/2"
},
"itemImages": null,
"displayOrder": null,
"volumeInLiter": null,
"isActive": true,
"isNew": null,
"videoUrl": "",
"videoSize": 0,
"formattedVideoSize": "0",
"pdfUrl": "",
"pdfSize": 0,
"formattedPdfSize": "0",
"similarItems": [],
"parentId": null,
"parentItem": null,
"hasDeclination": false,
"relatedItems": [],
"itemAttributes": [],
"tags": [
"tags4api"
],
"hasSerialNumbers": false,
"serialNumbers": null,
"organization": "entity1",
"dateCreated": "2015-12-16T16:38:44Z",
"lastUpdated": "2015-12-16T16:38:44Z"
},
…
]
} Failure OutputStatus: HTTP/1.1 400 Bad Request {
"error": "invalid_param",
"error_description": "The parameters [dateCreated_gta] you provided are not valid for this request."
}20.2 Show
Service: Show an item Description: Returns the requested item in json format when successful. Returns a json response, describing the failure condition when unsuccessful. URL: https://BASE_URL/api/VERSION/items/{id}: https://BASE_URL/api/VERSION/items/reference/{id}: GET Parameters: | Name | Description | Type | Required | Example values |
|---|
| id | The ID of the desired item | Long/String | yes | 123 |
Success OutputStatus: HTTP/1.1 200 OK {
"id": 706,
"reference": "bracelet-GRP09062",
"name": "Knot Band Bracelet",
"description": "",
"itemCategoryId": 2,
"itemCategory": {
"id": 2,
"reference": "Ref-01",
"name": "Jewelry",
"href": "/api/v1.0/itemCategories/2"
},
"itemImages": [{
"imageOrder": 1,
"smallImage": "BASE_URL/entity1-1450169988465/photoItem/0009afbb-ff5d-464e-bebb-4073ae7f1bc8-small.png",
"thumbnailImage": "BASE_URL/entity1-1450169988465/photoItem/0009afbb-ff5d-464e-bebb-4073ae7f1bc8-thumbnail.png",
"originalImage": "BASE_URL/entity1-1450169988465/photoItem/0009afbb-ff5d-464e-bebb-4073ae7f1bc8.png"
}],
"displayOrder": 1,
"volumeInLiter": null,
"isActive": false,
"isNew": true,
"videoUrl": "",
"videoSize": 0,
"formattedVideoSize": "0",
"pdfUrl": "",
"pdfSize": 0,
"formattedPdfSize": "0",
"similarItems": [],
"parentId": null,
"parentItem": null,
"hasDeclination": false,
"relatedItems": [],
"itemAttributes": [],
"tags": [
"bracelet",
"jewelry"
],
"hasSerialNumbers": false,
"serialNumbers": null,
"organization": "entity1",
"dateCreated": "2016-08-11T09:17:30Z",
"lastUpdated": "2016-08-11T09:17:30Z"
} Failure OutputStatus: HTTP/1.1 404 Not Found {
"error": "not_found",
"error_description": "The item with the id 7065 doesn't exist."
}Status: HTTP/1.1 400 Bad Request {
"error": "invalid_param_type",
"error_description": "The type of parameter id you provided is not valid for this request."
}20.3 Create
Service: Create an item Description: Returns the created item in json format when successful. Returns a json response, describing the failure condition when unsuccessful. URL: https://BASE_URL/api/VERSION/items : POST Request content type: application/x-www-form-urlencoded or multipart/form-data Parameters: | Name | Description | Type | Required | Example values |
|---|
| reference | | String | yes | | | name | | String | yes | | | description | | String | no | | | categoryId | The ID of the item category. | Long/String | - | | | isActive | By default, it is set to true | Boolean | no | true, false | | isNew | | Boolean | no | true, false | | displayOrder | | Integer | no | | | volumeInLiter | | Double | no | 1.5 | | pdfFile | Pdf size must be lower than 100 MB | pdf | no | | | video | Video size must be lower than 100 MB | webm, avi, mpeg , quicktime | no | | | image1 | Image size should not exceed 2 MB | jpg, gif, png, bmp | no | | | image2 | Image size should not exceed 2 MB | jpg, gif, png, bmp | no | | | image3 | Image size should not exceed 2 MB | jpg, gif, png, bmp | no | | | tags | Tags should not contain comma seperator | JSON list | no | ["bracelet","jewelry"] | | similarItems | List of similar items id | JSON list | no | [750,751] | | hasSerialNumbers | By default, it is set to false | Boolean | no | true, false | | hasDeclination | By default, it is set to false | Boolean | no | true, false | | useExternalId | By default, it is set to false. set it to true if you want to use external ids. | Boolean | no | true , false |
By default, if the parameter itemCategoryId is not specified, item will be added to the root item category. It will be required if there is many root categories.
Declination parameters (optional): Parameter name: attributeValues Parameter type: a json structure | Name | Description | Type | Required | Example values |
|---|
| itemReference | | String | yes | | | attributeValueId | | Integer | yes | |
Example:
attributeValues=[{itemReference:"tshirt_BLEU_S",attributeValueId:16},{itemReference:"tshirt_BLEU_S",attributeValueId:7},
{itemReference:"tshirt_ROUGE_XL",attributeValueId:6},{itemReference:"tshirt_ROUGE_XL",attributeValueId:9}]Success OutputStatus: HTTP/1.1 201 Created {
"id": 706,
"reference": "bracelet-GRP09062",
"name": "Knot Band Bracelet",
"description": null,
"itemCategoryId": 2,
"itemCategory": {
"id": 2,
"reference": "Ref-01",
"name": "Jewelry",
"href": "/api/v1.0/itemCategories/2"
},
"itemImages": null,
"displayOrder": 1,
"volumeInLiter": null,
"isActive": false,
"isNew": true,
"videoUrl": "",
"videoSize": 0,
"formattedVideoSize": "0",
"pdfUrl": "BASE_URL/entity1-1450169988465/itemPdfs/1471271200022_items_10_08_2016.pdf",
"pdfSize": 124487,
"formattedPdfSize": "121,6 Ko",
"similarItems": [],
"parentId": null,
"parentItem": null,
"hasDeclination": false,
"relatedItems": [],
"itemAttributes": [],
"tags": [],
"hasSerialNumbers": false,
"serialNumbers": null,
"organization": "entity1",
"dateCreated": "2016-08-11T09:17:30Z",
"lastUpdated": "2016-08-11T09:17:30Z"
} Failure OutputStatus: HTTP/1.1 400 Bad Request {
"error": "save_failed",
"error_description": "Failed to save instance."
}{
"error": "not_unique",
"error_description": "reference already used"
}{
"error": "missing_param",
"error_description": "Name parameter is missing"
}{
"error": "exceeded_file_size",
"error_description": "image size should not exceed 2Mo"
}{
"error": "unsupported_file_type",
"error_description": "image format not supported."
}Status: HTTP/1.1 404 Not Found {
"error": "not_found",
"error_description": "The Item Category with the id 2452 doesn't exist."
}20.4 Update
Service: Update an item Description: Returns the updated item in json format when successful. Returns a json response, describing the failure condition when unsuccessful. URL: https://BASE_URL/api/VERSION/items/{id}: https://BASE_URL/api/VERSION/items/reference/{id}: POST Request content type: application/x-www-form-urlencoded or multipart/form-data Parameters: | Name | Description | Type | Required | Example values |
|---|
| id | The ID of the desired item | Long/String | yes | 123 | | reference | | String | yes | | | name | | String | yes | | | description | | String | no | | | categoryId | The ID of the item category. | Long/String | - | | | isActive | By default, it is set to true | Boolean | no | true, false | | isNew | | Boolean | no | true, false | | displayOrder | | Integer | no | | | volumeInLiter | | Double | no | 1.5 | | pdfFile | | pdf | no | | | video | | webm, avi, mpeg , quicktime | no | | | image1 | | jpg, gif, png, bmp | no | | | image2 | | jpg, gif, png, bmp | no | | | image3 | | jpg, gif, png, bmp | no | | | tags | Tags should not contain comma seperator | JSON list | no | ["bracelet","jewelry"] | | similarItems | List of similar items id | JSON list | no | [750,751] | | hasSerialNumbers | By default, it is set to false | Boolean | no | true, false | | hasDeclination | By default, it is set to false | Boolean | no | true, false |
If item has already sold or reserved serial numbers, hasSerialNumbers parameter will be fixed to true. Declination parameters (optional): Parameter name: attributeValues Parameter type: a json structure | Name | Description | Type | Required | Example values |
|---|
| itemReference | | String | yes | | | attributeValueId | | Integer | yes | |
Success OutputStatus: HTTP/1.1 200 OK {
"id": 706,
"reference": "bracelet-GRP09062",
"name": "Knot Band Bracelet",
"description": null,
"itemCategoryId": 2,
"itemCategory": {
"id": 2,
"reference": "Ref-01",
"name": "Jewelry",
"href": "/api/v1.0/itemCategories/2"
},
"itemImages": null,
"displayOrder": 1,
"volumeInLiter": null,
"isActive": false,
"isNew": true,
"videoUrl": "",
"videoSize": 0,
"formattedVideoSize": "0",
"pdfUrl": "",
"pdfSize": 0,
"formattedPdfSize": "0",
"similarItems": [],
"parentId": null,
"parentItem": null,
"hasDeclination": false,
"relatedItems": [],
"itemAttributes": [],
"tags": [],
"hasSerialNumbers": false,
"serialNumbers": null,
"organization": "entity1",
"dateCreated": "2016-08-11T09:17:30Z",
"lastUpdated": "2016-08-12T10:17:30Z"
} Failure OutputStatus: HTTP/1.1 404 Not Found {
"error": "not_found",
"error_description": "The item with the id 706 doesn't exist."
}20.5 Upsert
Service: Upsert an item Description: This web service is used to insert an item object to the database if it does not already exist, or update it. URL with external_id: https://BASE_URL/api/VERSION/items/reference/{id}: POST Request content type: application/x-www-form-urlencoded or multipart/form-data Parameters: | Name | Description | Type | Required | Example values |
|---|
| reference | | String | yes | | | name | | String | yes | | | description | | String | no | | | categoryId | The ID of the item category. | String | - | | | isActive | By default, it is set to true | Boolean | no | true, false | | isNew | | Boolean | no | true, false | | displayOrder | | Integer | no | | | volumeInLiter | | Double | no | 1.5 | | pdfFile | Pdf size must be lower than 100 MB | pdf | no | | | video | Video size must be lower than 100 MB | webm, avi, mpeg , quicktime | no | | | image1 | Image size should not exceed 2 MB | jpg, gif, png, bmp | no | | | image2 | Image size should not exceed 2 MB | jpg, gif, png, bmp | no | | | image3 | Image size should not exceed 2 MB | jpg, gif, png, bmp | no | | | tags | Tags should not contain comma seperator | JSON list | no | ["bracelet","jewelry"] | | similarItems | List of similar items id | JSON list | no | [750,751] | | hasSerialNumbers | By default, it is set to false | Boolean | no | true, false | | hasDeclination | By default, it is set to false | Boolean | no | true, false | | withLabel | By default, if isNew is true, it is set to false | Boolean | no | true, false | | labelNote | No more than 7 characters | String | no | Faves | | labelColor | Hexadecimal color code | String | no | #32bcb0 |
By default, if the parameter itemCategoryId is not specified, item will be added to the root item category. It will be required if there is many root categories.
Declination parameters (optional): Parameter name: attributeValues Parameter type: a json structure | Name | Description | Type | Required | Example values |
|---|
| itemReference | | String | yes | | | attributeValueId | | Integer | yes | |
Example:
attributeValues=[{itemReference:"tshirt_BLEU_S",attributeValueId:16},{itemReference:"tshirt_BLEU_S",attributeValueId:7},
{itemReference:"tshirt_ROUGE_XL",attributeValueId:6},{itemReference:"tshirt_ROUGE_XL",attributeValueId:9}]Success OutputStatus: HTTP/1.1 201 Created {
"id": 706,
"reference": "bracelet-GRP09062",
"name": "Knot Band Bracelet",
"description": null,
"itemCategoryId": 2,
"itemCategory": {
"id": 2,
"reference": "Ref-01",
"name": "Jewelry",
"href": "/api/v1.0/itemCategories/2"
},
"itemImages": null,
"displayOrder": 1,
"volumeInLiter": null,
"isActive": false,
"isNew": true,
"videoUrl": "",
"videoSize": 0,
"formattedVideoSize": "0",
"pdfUrl": "BASE_URL/entity1-1450169988465/itemPdfs/1471271200022_items_10_08_2016.pdf",
"pdfSize": 124487,
"formattedPdfSize": "121,6 Ko",
"similarItems": [],
"parentId": null,
"parentItem": null,
"hasDeclination": false,
"relatedItems": [],
"itemAttributes": [],
"tags": [],
"hasSerialNumbers": false,
"serialNumbers": null,
"organization": "entity1",
"dateCreated": "2016-08-11T09:17:30Z",
"lastUpdated": "2016-08-11T09:17:30Z"
} Failure OutputStatus: HTTP/1.1 400 Bad Request {
"error": "save_failed",
"error_description": "Failed to save instance."
}{
"error": "not_unique",
"error_description": "reference already used"
}{
"error": "missing_param",
"error_description": "Name parameter is missing"
}{
"error": "exceeded_file_size",
"error_description": "image size should not exceed 2Mo"
}{
"error": "unsupported_file_type",
"error_description": "image format not supported."
}Status: HTTP/1.1 404 Not Found {
"error": "not_found",
"error_description": "The Item Category with the id 2452 doesn't exist."
}20.6 Delete
Service: Delete an item Description: Returns a json response. URL: https://BASE_URL/api/VERSION/items/{id}: https://BASE_URL/api/VERSION/items/reference/{id}: DELETE Parameters: | Name | Description | Type | Required | Example values |
|---|
| id | The ID of the desired item | Long/String | yes | 123 |
Success OutputStatus: HTTP/1.1 200 OK {
"success": "true",
"success_description": "Instance deleted successfully"
} Failure OutputStatus: HTTP/1.1 400 Bad Request {
"error": "delete_failed",
"error_description": "Failed to delete instance."
}Status: HTTP/1.1 404 Not Found {
"error": "not_found",
"error_description": "The item with the id 706 doesn't exist."
}
|
|
