REST Object API Read V2
Version 2 of the Object Read API introduces a new parameter "includeIds" and a streamlined response payload which no longer contains the extra "_current" element. Besides that, the response payload's _data element can directly be used for the Write API.
If a field or entity is supported by the Object API V2 has now been bound to the newly introduced "supportsObjectApi" flag in the repository. A better control over the fields and entities which are supported is possible with this.
Read Requests
Single Item
|
URL Pattern |
/object/{entity-identifier}/{entity_item} |
||||||||||
|
Method |
GET |
||||||||||
|
Accept |
application/json application/xml If multiple accept headers are defined, they will be evaluated by their order. |
||||||||||
|
Example |
/rest/V2.0/object/Article/4711@1 /rest/V2.0/object/Article/'myItem'@'myCatalog' |
||||||||||
|
Return Codes |
|
Multiple Items
This endpoint provides a multi-item interface in which the client can provide multiple items which should be returned in one call. As query parameters do have a size limitation, this api is designed as POST. This api has restrictions on the number of items which can be called. In case the limit is exceeded a corresponding return code is provided.
Contrary to the single item GET request, a missing object permission or an unknown item id does not lead to an error return code; it will just not be returned.
|
URL Pattern |
/object/{entity-identifier}/byItems |
||||||||
|
Method |
POST |
||||||||
|
Headers |
|
||||||||
|
Form Parameters |
|
||||||||
|
Example |
/rest/V2.0/object/Article/byItems |
||||||||
|
Return Codes |
|
Query Parameters
Please note that the qualification filter applies to all requested sub-entities which have this qualification. So, for example, if you filter for language=English, the ArticleLang and ArticleAttributeValueLang entities will both only return the English values!
|
Parameter |
Required |
Default |
Datatype |
Parameter description |
Example |
|
entityFilter |
no |
none |
String |
Comma separated list of entity identifiers which should be part of the result. If omitted, the full object with all data is returned. We recommend to provide a list of entities which are required in order to gain performance. Note: In case an entityFilter is provided, also the root entity is a filter value. So by only providing the root entity as filter value, only the fields of the root level are returned in the data. |
Only return the root fields: Only return the root fields, and the sales prices Only return the language specific data like Short and Long Description |
|
qualificationFilter |
no |
none |
String |
This parameter allows to restrict the output to certain qualifications. One example would be a filter so that only Euro and US-Dollar prices for the customer Informatica are returned. The filter string is a comma-separated list of qualification settings. A qualification setting is a qualification name followed by a comma-separated list of values which is put into parentheses . The qualification name is defined in the repository and is included in the Meta-API. |
Example for prices in Euro and US-Dollar and customer Informatica: |
|
revision |
no |
root |
ENTITY_ITEM |
The revision for which the data should be retrieved |
revision='root' revision=1 revision='myRevisionIdentifier' revision=4711 (where 4711 is the internal id of the revision). |
|
includeLabels |
no |
false |
boolean |
If set to true, the returned document will contain _label elements for all fields or qualifications which have an enumeration. The label will be returned in the locale of the request like this: "orderUnit" : { "_current" : { "_key" : { "_entityId" : 3100, "_internalId" : "932", "_externalId" : "'C62'" }, "_code" : "C62", "_label" : "piece" }} |
includeLabels=true includeLabels=false |
|
includeIds |
no |
false |
boolean |
If set to false, the payload avoids to contain any internal ids which might be system specific. This specifically applies to the ENTITY_ITEM datatype which will then no longer contain the "_internalId" element, only the "_externalId". Also the "_entityId" element will be replaced by an "entity" element which then holds the alphanumeric identifier of the entity and not it's numeric id. While reading and writing to the same Product 360 environment, we always recommend to include the ids since write performance is increased as no internal lookup needs to be done. In case the object is read for a 3rd party system, you might very well disable the internalIds to further reduce the response size! |
includeIds=true includeIds=false |
|
includeMimeValueArchive |
no |
false |
boolean |
If set to true a ZIP Archive will be provided on the server which can be downloaded using the File API. This archive will contain all MIME_VALUE binaries of all objects which have been returned by the call to the object API. |
Permissions
Object Permissions
The user needs to have the READ object permission for this API. In case he doesn't, the api returns HTTP 403 (forbidden) in case of the single item call with GET, and skip this item in case of the multiple items call.
Field Permissions
The user needs to have the READ field permissions for a field. If he doesn't, the field will not be part of the data element, but no error is returned.
Qualification Permissions (aka Qualified Field Permissions)
The user needs to have the READ permission for a qualification, e.g. for Language = English. If he doesn't, sub-entities which are qualified for this will not be part of the data element, but no error is returned.
Result
Repository Entities and Fields
Names
A new repository property "shortIdentifier" has been added in the custom section which is used to define the entity and field names for the json structure. The short identifier is unique within its parent entity only!
The standard repository already contains a short identifier for all fields and enabled qualifications.
Datatypes
ENTITY_ITEM objects. Depending on the includeIds parameter they contain a different subset:
includeIds = true: _entityId, _internalId and _externalId
includeIds = false: _entity and _externalId
MIME_VALUE objects always contain the relative _filePath, the _label and the _mimeType
timestamp: ISO 8601, e.g.: 2012-04-23T18:25:43.511Z
date: ISO 8601, e.g.: 2019-07-04
numbers: standard JSON
"no value" is either provided as null, or the attribute is not in the document.
Empty string is returned as null, which is omitted when possible!
Enumeration fields
_key: always holds the unique key of the enumeration entry
In case the enumeration field is of datatype ENTITY_ITEM, then the key will be provided with the ENTITY_ITEM syntax (see above)
The key is omitted in case includeIds parameter is set to false, and the enumeration entry does have a code._code: the external code of the enumeration entry, if the enum entry has one, and it differs from the key!
_label: the locale dependent label of the enumeration entry. Only if includeLabels is set to true. The locale of the http request is used for this.
Meta attributes
All meta attributes are prefixed with an underscore.
_entity = the root entity identifier
_entityItem = the entity item in the ENTITY_ITEM syntax
_revision = the revision of the data as ENTITY_ITEM
_data = The actual entity item's data
_qualification = the qualification of the record. The combination of the qualification values in the qualification object define this record as unique within its parent.
Data Element
In order to be part of the data element of the object api, a sub-entity or field must fulfill multiple criteria:
The entity or field must be active in the repository
The entity or field must have supportsObjectApi = true in the repository.
In case the corresponding FieldType or EntityType does not support object api, enabling it in the custom area has no effect.The user must have READ permission for the Entity or Field
The user must have READ permission for the qualification of the sub-entity
The field must must not be a password Field in the repository
Qualifications must be editable in the repository
Entities, Fields or Qualifications which do not comply to any of these points will be omitted in the data element. No exception is thrown.
Example Result
|
includeIds = true |
includeIds = false |
{ |
{ |
Characteristic Values
Characteristic values are rendered in a specialized structure in order to honor their hierarchical nature.
This structure is not identical to the repository as it is fully hierarchical. This is the reason for extra meta attributes which help to not get in conflict with repository based data.
Additional Meta Attributes
_characteristicRecords
Top level element for all characteristic records_recordLang
Language specific record values. In case the characteristic is not language specific, the qualification for "not language specific" is returned (-1 or xxz)
In case the value of the record is a lookup value and the includeLabels parameter has been set, an additional _label element is provided._children
children of the current characteristic record_datatype
The characteristic data type - to be able to interpret the values even in case the characteristic is no longer in the system_formatPattern
The format pattern of the characteristic - to be able to format the values even in case the characteristic is no longer in the system
Response Examples
|
includeIds = true |
includeIds = false |
{ |
{ |
Examples
Please see the attached postman example collection for you convenience: ObjectAPI.postman_collection.json
Get Item by ID
curl --location --request GET 'http://localhost:1512/rest/V2.0/object/Article/14260@1120' \--header 'Content-Type: application/json' \--header 'Authorization: Basic cmVzdDpoZWlsZXI='Get Item by Identifier As XML
curl --location --request GET 'http://localhost:1512/rest/V2.0/object/Article/'\''supplierAID-42'\''@'\''MySupplierCatalog'\''' \--header 'Content-Type: application/xml' \--header 'Authorization: Basic cmVzdDpoZWlsZXI='Get Filtered Item (entity and qualification filter)
curl --location --request GET 'http://localhost:1512/rest/V2.0/object/Article/'\''supplierAID-42'\''@'\''MySupplierCatalog'\''?qualificationFilter=language(eng)&entityFilter=ArticleLang' \--header 'Content-Type: application/json' \--header 'Authorization: Basic cmVzdDpoZWlsZXI='