REST API Tutorial - List Read for Root Entities
The list read for root entities is similar to a root entity table in the Rich Client.
The following information has to be specified for a list read:
1. Which objects should be included (rows) -> Report
List of available reports:
http://localhost:1501/rest/V1.0/list/info
Please note that there is a general report called bySearch which allows powerful search queries (see also REST Search Query Language).
General information about reports: Entity Reporting
2. Which fields are required (columns)
The fields are specified in the URL parameter fields
Fields of sub entities have to be qualified, see also REST Field Qualification.
3. Options
Various options are available, like sort order, paging and formatting information. They are described in section Parameters in REST List API Read for Root EntitiesPlease note that the options includeLabels and cacheId have an impact on performance (unfortunately, the default settings are not the fastest settings). If not otherwise required, set includeLabels to false and cacheId to no-cache.Note that the locale, the request is executed in, has to be set directly in the http header (property Accept-Language, the format is <language>-<country>, e.g., en-US or de-DE).
Examples
Root entity fields only
Report:
byCatalog whereby parameter catalog is set to RestTutorial
Fields:
Article.SupplierAIDArticle.ManufacturerNameArticle.MainSupplierArticle.QuantityMinOptions:metaData is set to true (shows meta information for the specified fields)pageSize is set to -1 (return all items)chacheId is set to no-cache (result of report execution is not cached, paged access is not possible)GET http://localhost:1501/rest/V1.0/list/Article/byCatalog?catalog=RestTutorial&fields=Article.SupplierAID,Article.ManufacturerName,Article.MainSupplier,Article.QuantityMin&metaData=true&pageSize=-1&cacheId=no-cache
Root fields and qualified sub entity fields
Fields:
Article.SupplierAID
ArticleLang.DescriptionShort(
German
)
ArticleLang.DescriptionShort(
English
)
ArticleAttributeValue.Value(Length,"
Language independent
",DEFAULT)
ArticleAttributeValue.Value("Front Color",English,DEFAULT)
GET http://localhost:1501/rest/V1.0/list/Article/byCatalog?catalog=RestTutorial&fields=Article.SupplierAID, ArticleLang.DescriptionShort(German),ArticleLang.DescriptionShort(English),ArticleAttributeValue.Value(Length,"Language independent",DEFAULT),ArticleAttributeValue.Value("Front Color",English,DEFAULT)&metaData=true
Remark:
If a qualification is an enumeration, the label, one of the synonyms or the key can be used.
So instead of ArticleLang.DescriptionShort( German ) also the following expressions are possible:
ArticleLang.DescriptionShort(
de
) (synoym)
ArticleLang.DescriptionShort(
7
) (key)
Transition field access
Since 7.1.03 it is possible to use transition fields that allow to access values of linked objects directly (currently read access only).For example to get the acronym of the main supplier from the example above, Article.MainSupplier->Party.Acronym can be used.See also REST Transition Fields.
Fields:
Article.SupplierAID
Article.MainSupplier->Party.Name
Article.MainSupplier->Party.Acronym
GET http://localhost:1501/rest/V1.0/list/Article/byCatalog?catalog=RestTutorial&fields=Article.SupplierAID,Article.MainSupplier->Party.Name,Article.MainSupplier->Party.Acronym&metaData=true&pageSize=-1
Paged access
Use the parameters startIndex, pageSize and cacheId to perform a page based access.
First call (without parameter cacheId ):
GET http://localhost:1501/rest/V1.0/list/Article/byCatalog?catalog=RestTutorial&fields=Article.SupplierAID,ArticleLang.DescriptionShort(German)&startIndex=0&pageSize=1
Second call (with parameter cacheId):
GET http://localhost:1501/rest/V1.0/list/Article/byCatalog?catalog=RestTutorial&fields=Article.SupplierAID,ArticleLang.DescriptionShort(German)&startIndex=1&pageSize=1&cacheId=<Returned cacheId>