(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

Method: GET

Parameters:

Pagination parameters:

NameDescriptionTypeRequiredPossible values
maxLimits the number of resources requested to return.Integerno 
offsetTells where to start returning records from the entire set of results.Integerno 
orderOrders ascending or descending.Integernoasc,desc
sortOrders the results by the specified field.Stringno 

The max parameter is set to 100 by default.

Filters parameters:

NameDescriptionTypeRequiredExample values
dateCreated_gtFilters by the resource's creation date time and operator greater thanDateno2016-08-15T14:52:48Z
dateCreated_gteFilters by the resource's creation date time and operator greater than or equalDateno 
dateCreated_ltFilters by the resource's creation date time and operator less thanDateno 
dateCreated_lteFilters by the resource's creation date time and operator less than or equalDateno 
lastUpdated_gtFilters by the resource's last-modified date time and operator greater thanDateno 
lastUpdated_gteFilters by the resource's last-modified date time and operator greater than or equalDateno 
lastUpdated_ltFilters by the resource's last-modified date time and operator less thanDateno 
lastUpdated_lteFilters by the resource's last-modified date time and operator less than or equalDateno 
referenceWildcard search by the resource's referenceStringnoreference=Ref-6* , reference=*ef-6 , reference=*ef-6*
nameWildcard search by the resource's nameStringno 

Dates should be formatted as the ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ)

Success Output

Status: 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 Output

Status: 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}

URL with external_id:

https://BASE_URL/api/VERSION/items/reference/{id}

Method: GET

Parameters:

NameDescriptionTypeRequiredExample values
idThe ID of the desired itemLong/Stringyes123

Success Output

Status: 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 Output

Status: 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

Method: POST

Request content type: application/x-www-form-urlencoded or multipart/form-data

Parameters:

NameDescriptionTypeRequiredExample values
reference Stringyes 
name Stringyes 
description Stringno 
categoryIdThe ID of the item category.Long/String- 
isActiveBy default, it is set to trueBooleannotrue, false
isNew Booleannotrue, false
displayOrder Integerno 
volumeInLiter Doubleno1.5
pdfFilePdf size must be lower than 100 MBpdfno 
videoVideo size must be lower than 100 MBwebm, avi, mpeg , quicktimeno 
image1Image size should not exceed 2 MBjpg, gif, png, bmpno 
image2Image size should not exceed 2 MBjpg, gif, png, bmpno 
image3Image size should not exceed 2 MBjpg, gif, png, bmpno 
tagsTags should not contain comma seperatorJSON listno["bracelet","jewelry"]
similarItemsList of similar items idJSON listno[750,751]
hasSerialNumbersBy default, it is set to falseBooleannotrue, false
hasDeclinationBy default, it is set to falseBooleannotrue, false
useExternalIdBy default, it is set to false. set it to true if you want to use external ids.Booleannotrue , 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

NameDescriptionTypeRequiredExample values
itemReference Stringyes 
attributeValueId Integeryes 

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 Output

Status: 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 Output

Status: 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}

URL with external_id:

https://BASE_URL/api/VERSION/items/reference/{id}

Method: POST

Request content type: application/x-www-form-urlencoded or multipart/form-data

Parameters:

NameDescriptionTypeRequiredExample values
idThe ID of the desired itemLong/Stringyes123
reference Stringyes 
name Stringyes 
description Stringno 
categoryIdThe ID of the item category.Long/String- 
isActiveBy default, it is set to trueBooleannotrue, false
isNew Booleannotrue, false
displayOrder Integerno 
volumeInLiter Doubleno1.5
pdfFile pdfno 
video webm, avi, mpeg , quicktimeno 
image1 jpg, gif, png, bmpno 
image2 jpg, gif, png, bmpno 
image3 jpg, gif, png, bmpno 
tagsTags should not contain comma seperatorJSON listno["bracelet","jewelry"]
similarItemsList of similar items idJSON listno[750,751]
hasSerialNumbersBy default, it is set to falseBooleannotrue, false
hasDeclinationBy default, it is set to falseBooleannotrue, 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

NameDescriptionTypeRequiredExample values
itemReference Stringyes 
attributeValueId Integeryes 

Success Output

Status: 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 Output

Status: 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}

Method: POST

Request content type: application/x-www-form-urlencoded or multipart/form-data

Parameters:

NameDescriptionTypeRequiredExample values
reference Stringyes 
name Stringyes 
description Stringno 
categoryIdThe ID of the item category.String- 
isActiveBy default, it is set to trueBooleannotrue, false
isNew Booleannotrue, false
displayOrder Integerno 
volumeInLiter Doubleno1.5
pdfFilePdf size must be lower than 100 MBpdfno 
videoVideo size must be lower than 100 MBwebm, avi, mpeg , quicktimeno 
image1Image size should not exceed 2 MBjpg, gif, png, bmpno 
image2Image size should not exceed 2 MBjpg, gif, png, bmpno 
image3Image size should not exceed 2 MBjpg, gif, png, bmpno 
tagsTags should not contain comma seperatorJSON listno["bracelet","jewelry"]
similarItemsList of similar items idJSON listno[750,751]
hasSerialNumbersBy default, it is set to falseBooleannotrue, false
hasDeclinationBy default, it is set to falseBooleannotrue, 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

NameDescriptionTypeRequiredExample values
itemReference Stringyes 
attributeValueId Integeryes 

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 Output

Status: 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 Output

Status: 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}

URL with external_id:

https://BASE_URL/api/VERSION/items/reference/{id}

Method: DELETE

Parameters:

NameDescriptionTypeRequiredExample values
idThe ID of the desired itemLong/Stringyes123

Success Output

Status: HTTP/1.1 200 OK

{
  "success": "true",
  "success_description": "Instance deleted successfully"
}

Failure Output

Status: 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."
}