(Quick Reference)
23 Categories of items - Reference Documentation
Version: 2.1
23 Categories of items
23.1 List
Service: List of item categories
Description: This web service return the list of item categories with consideration to the specified organization in JSON format
URL:
https://BASE_URL/api/VERSION/itemCategories
: GET
Parameters:
Pagination parameters:
| Name | Description | Type | Required | Possible values |
|---|
| offset | Tells where to start returning records from the entire set of results | Integer | No | |
| max | limits the number of resources requested to return | Integer | No | |
| sort | Orders the results by the specified field | String | No | |
| order | Orders ascending (ASC) or descending DESC | Integer | No | asc, desc |
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 | |
| isRoot | Filters by root categories, and vice versa | boolean | no | true,false |
Dates should be formatted as the ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ)
Success Output
Success case: response.status=200
{
"paging": {
"total": 2,
"max": 100,
"offset": 0,
"previous": null,
"next": null
},
"data": [
{
"id": 255,
"name": "Item Category255",
"isRoot": true,
"isGoodiesCategory": false,
"isAsset": false,
"parentId": null,
"parentCategory": null,
"reference": "R100",
"description": null,
"image": null,
"organization": "Lyon",
"displayOrder": null,
"isActive" : true,
"dateCreated": "2016-08-18T08:21:05Z",
"lastUpdated": "2016-08-18T08:21:05Z"
},
{
"id": 256,
"name": "Item Category256",
"isRoot": true,
"isGoodiesCategory": false,
"isAsset": false,
"parentId": null,
"parentCategory": null,
"reference": "R200",
"description": null,
"image": null,
"organization": "Lyon",
"displayOrder": 6,
"isActive" : false,
"dateCreated": "2016-08-18T08:21:21Z",
"lastUpdated": "2016-08-18T08:21:21Z"
}
]
}To get resized images, add prefix
small_ or
medium_ to the link url before the image's name, for example:
<BASE_URL>/Lyon-1447055487659/photoItemCategory/medium_1471513158851_forfix.png
Failure Output
Failure case:response.status = 400
{
"error": "invalid_param",
"error_description": "The parameters [dateCreated_gta] you provided are not valid for this request."
}{
"error": "invalid_datetime_format",
"error_description": "Invalid datetime filter (not ISO-8601 formatted): [2016-08-1Z]"
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}23.2 Show
Service: Show an item category
Description: This web service return an existing item category details of the specified id in JSON format
URL:
https://BASE_URL/api/VERSION/itemCategories/{id}:
https://BASE_URL/api/VERSION/itemCategories/reference/{id}: GET
Parameters:
| Name | Description | Type | Required | Example values |
|---|
| id | id of the wanted item category | Long/String | Yes | 777 |
Success Output
Success case: response.status=200
{
"id": 255,
"name": "Brigui",
"isRoot": true,
"isGoodiesCategory": false,
"isAsset": false,
"parentId": null,
"parentCategory": null,
"reference": "R100",
"description": null,
"image": null,
"organization": "Lyon",
"displayOrder": 6,
"isActive" : true,
"dateCreated": "2016-08-18T08:21:05Z",
"lastUpdated": "2016-08-18T08:21:05Z"
}To get resized images, add prefix
small_ or
medium_ to the link url before the image's name, for example:
<BASE_URL>/Lyon-1447055487659/photoItemCategory/medium_1471513158851_forfix.png
Failure Output
Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The item category with the id 3 doesn't exist."
} Failure case:response.status = 400
{
"error": "invalid_param_type",
"error_description": "The type of parameter id you provided is not valid for this request."
}23.3 Delete
Service: Delete an item category
Description: This web service is used in order to delete an existing item category object from the database
URL:
https://BASE_URL/api/VERSION/itemCategories/{id}:
https://BASE_URL/api/VERSION/itemCategories/reference/{id}: DELETE
Parameters:
| Name | Description | Type | Required | Examples values |
|---|
| id | Id of the desired item category to delete | Long/String | Yes | 777 |
Success Output
Success case: response.status=200
{
"success": "true",
"success_description": "Instance deleted successfully"
} Failure Output
Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The item category with the id 3 doesn't exist."
} Failure case:response.status = 400
{
"error": "invalid_param_type",
"error_description": "The type of parameter id you provided is not valid for this request."
}{
"error": "delete_failed",
"error_description": "Failed to delete instance"
}{
"error": "delete_not_authorized",
"error_description": "item category with id 1 is the last root category in the organization."
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}23.4 Update
Service: Update an item Category
Description: This web service is used to update an existing item category object to the database
URL:
https://BASE_URL/api/VERSION/itemCategories/{id}:
https://BASE_URL/api/VERSION/itemCategories/reference/{id}: POST
Request content type: application/x-www-form-urlencoded or multipart/form-data
Parameters:
| Name | Description | Type | Required | Example values |
|---|
| reference | the new reference of the item category | String | Yes | |
| name | the new name of the item category | String | Yes | |
| description | some details of the updated category | String | No | |
| isActive | | Boolean | No | false |
| isGoodies | The default value is set to false | Boolean | No | true |
| isAsset | The default value is set to false | Boolean | No | false, true |
| isRoot | this parameter is used to declared if the new category is a root or not and by default it take false value | Boolean | No | false |
| parentId | the id of the parent category | LOng/String | | 2 |
| fileUpload | image specified to the new item category it can be jpg, gif, png, bmp | multipart | No | |
| displayOrder | the order of appearance of an item category | Integer | No | 5 |
reference must be unique
parentId is not required only if isRoot is set to true ,Or isRoot is set to false and there is exactly only one category in the database
Only one of those three attribute (isRoot,isGoodies,isAsset) can be set to true
Success Output
Success case: response.status=201
{
"id": 257,
"name": "new Cate",
"isRoot": false,
"isGoodiesCategory": false,
"isAsset": false,
"parentId": 255,
"parentCategory": {
"id": 255,
"reference": "R100",
"name": "Brigui",
"href": "/api/v1.0/itemCategories/255"
},
"reference": "RC-999",
"description": null,
"image": "BASE_URL/Lyon-1447055487659/photoItemCategory/1471513158851_forfix.png",
"organization": "Lyon",
"displayOrder": 2,
"isActive": true,
"dateCreated": "2016-08-18T09:39:18Z",
"lastUpdated": "2016-08-18T09:39:18Z"
}To get resized images, add prefix
small_ or
medium_ to the link url before the image's name, for example:
<BASE_URL>/Lyon-1447055487659/photoItemCategory/medium_1471513158851_forfix.png
Failure Output
Failure case:response.status = 400
{
"error": "missing_param",
"error_description": "reference parameter is missing"
}{
"error": "not_unique",
"error_description": "reference already used"
}{
"error" : "invalid_param_type",
"error_description" : "An invalid value was specified for parameter: isRoot (must be a boolean: true or false)"
}{
"error": "exceeded_file_size",
"error_description": "image size should not exceed 2Mo"
}{
"error": "unsupported_file_type",
"error_description": "image format not supported."
}{
"error": "invalid_param_type",
"error_description": "An invalid value was specified for parameter: displayOrder (must be positive)"
}{
"error": "update_not_authorized",
"error_description": "the item category must be either a root category or an asset or a goodie"
}{
"error": "save_failed",
"error_description": "Failed to save instance"
}{
"error": "update_not_authorized",
"error_description": "Organization should have at least one root category of item."
} Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The item category with the id 4444 doesn't exist."
}{
"error": "not_found",
"error_description": "The parent item category with the id null doesn't exist."
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}23.5 Upsert
Service: Upsert an item Category
Description: This web service is used to insert an item category object to the database if it does not already exist, or update it.
URL with external_id:
https://BASE_URL/api/VERSION/itemCategories/reference/{id}: POST
Request content type: application/x-www-form-urlencoded or multipart/form-data
Parameters:
| Name | Description | Type | Required | Example values |
|---|
| reference | the reference of the new item category | String | Yes | |
| name | the name of the new item category | String | Yes | |
| description | some details of the new category | String | No | |
| isActive | | Boolean | No | false |
| isGoodies | The default value is set to false | Boolean | No | true |
| isAsset | The default value is set to false | Boolean | No | false, true |
| isRoot | this parameter is used to declared if the new category is a root or not and by default it take false value | Boolean | No | false |
| parentId | the id of the parent | String | | 2 |
| fileUpload | image specified to the new item category it can be jpg, gif, png, bmp | multipart | No | |
| displayOrder | the order of appearance of an item category | Integer | No | 5 |
reference must be unique
parentId is not required only if isRoot is set to true ,Or isRoot is set to false and there is exactly only one category in the database
Only one of those three attribute (isRoot,isGoodies,isAsset) can be set to true
Success Output
Success case: response.status=201
{
"id": 257,
"name": "new Cate",
"isRoot": false,
"isGoodiesCategory": false,
"isAsset":false,
"parentId": 255,
"parentCategory": {
"id": 255,
"reference": "R100",
"name": "Brigui",
"href": "/api/v1.0/itemCategories/255"
},
"reference": "RC-999",
"description": null,
"image": "BASE_URL/Lyon-1447055487659/photoItemCategory/1471513158851_forfix.png",
"organization": "Lyon",
"displayOrder": 9,
"isActive" : true,
"dateCreated": "2016-08-18T09:39:18Z",
"lastUpdated": "2016-08-18T09:39:18Z"
}To get resized images, add prefix
small_ or
medium_ to the link url before the image's name, for example:
<BASE_URL>/Lyon-1447055487659/photoItemCategory/medium_1471513158851_forfix.png
Failure Output
Failure case:response.status = 400
{
"error": "missing_param",
"error_description": "reference parameter is missing"
}{
"error": "not_unique",
"error_description": "reference already used"
}{
"error" : "invalid_param_type",
"error_description" : "An invalid value was specified for parameter: isRoot (must be a boolean: true or false)"
}{
"error": "exceeded_file_size",
"error_description": "image size should not exceed 2Mo"
}{
"error": "unsupported_file_type",
"error_description": "image format not supported."
}{
"error": "invalid_param_type",
"error_description": "An invalid value was specified for parameter: displayOrder (must be positive)"
}{
"error": "save_not_authorized",
"error_description": "the item category must be either a root category or an asset or a goodie"
}{
"error": "save_failed",
"error_description": "Failed to save instance"
} Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The parent item category with the id null doesn't exist."
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}23.6 Create
Service: Save an item Category
Description: This web service is used to add a new item category object to the database
URL:
https://BASE_URL/api/VERSION/itemCategories
: POST
Request content type: application/x-www-form-urlencoded or multipart/form-data
Parameters:
| Name | Description | Type | Required | Example values |
|---|
| reference | the reference of the new item category | String | Yes | |
| name | the name of the new item category | String | Yes | |
| description | some details of the new category | String | No | |
| isActive | | Boolean | No | false |
| isGoodies | The default value is set to false | Boolean | No | true |
| isAsset | The default value is set to false | Boolean | No | false, true |
| isRoot | this parameter is used to declared if the new category is a root or not and by default it take false value | Boolean | No | false |
| parentId | the id of the parent | LOng/String | | 2 |
| fileUpload | image specified to the new item category it can be jpg, gif, png, bmp | multipart | No | |
| displayOrder | the order of appearance of an item category | Integer | No | 5 |
| useExternalId | By default, it is set to false. set it to true if you want to use external ids. | Boolean | no | true , false |
reference must be unique
parentId is not required only if isRoot is set to true ,Or isRoot is set to false and there is exactly only one category in the database
Only one of those three attribute (isRoot,isGoodies,isAsset) can be set to true
Success Output
Success case: response.status=201
{
"id": 257,
"name": "new Cate",
"isRoot": false,
"isGoodiesCategory": false,
"isAsset":false,
"parentId": 255,
"parentCategory": {
"id": 255,
"reference": "R100",
"name": "Brigui",
"href": "/api/v1.0/itemCategories/255"
},
"reference": "RC-999",
"description": null,
"image": "BASE_URL/Lyon-1447055487659/photoItemCategory/1471513158851_forfix.png",
"organization": "Lyon",
"displayOrder": 9,
"isActive" : true,
"dateCreated": "2016-08-18T09:39:18Z",
"lastUpdated": "2016-08-18T09:39:18Z"
}To get resized images, add prefix
small_ or
medium_ to the link url before the image's name, for example:
<BASE_URL>/Lyon-1447055487659/photoItemCategory/medium_1471513158851_forfix.png
Failure Output
Failure case:response.status = 400
{
"error": "missing_param",
"error_description": "reference parameter is missing"
}{
"error": "not_unique",
"error_description": "reference already used"
}{
"error" : "invalid_param_type",
"error_description" : "An invalid value was specified for parameter: isRoot (must be a boolean: true or false)"
}{
"error": "exceeded_file_size",
"error_description": "image size should not exceed 2Mo"
}{
"error": "unsupported_file_type",
"error_description": "image format not supported."
}{
"error": "invalid_param_type",
"error_description": "An invalid value was specified for parameter: displayOrder (must be positive)"
}{
"error": "save_not_authorized",
"error_description": "the item category must be either a root category or an asset or a goodie"
}{
"error": "save_failed",
"error_description": "Failed to save instance"
} Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The parent item category with the id null doesn't exist."
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}
