Vertical sectioning

Restricting or expanding the returned properties

It is a good practice to restrict the properties returned by the ObjectAPI to reduce the amount of transferred data. However, when we need to add more properties by including associated data as well, we use the select query parameter for this purpose.

Default Value

If we do not provide the select query parameter (or an empty value), by default, all properties are added, including the ones that are aggregated into the Object definition itself. The properties that are returned can be seen in the OpenAPI documentation: all simple properties and complex properties whose schema names start with the name of the main schema.

For example, in the case of customers, the main schema name is U4ERP.Objects.Customer. All simple properties like aliasName, companyId, and invoiceCode are included. The complex property invoice (and its simple properties) is included since its schema name is U4ERP.Objects.Customer.Invoice. The same case applies for the payment complex property. Meanwhile, the workflow complex property is not included, since it is not an aggregated part of the main object, as its schema name also indicates: U4ERP.Objects.WorkflowTransactions.

erDiagram
    "U4ERP.Objects.Customer"  ||--o| "U4ERP.Objects.Customer.Invoice" : invoice
    "U4ERP.Objects.Customer"  ||--o| "U4ERP.Objects.Customer.Payment" : payment
    "U4ERP.Objects.Customer"  ||--o| "U4ERP.Objects.ContactPoints" : contactPoints
    "U4ERP.Objects.Customer"  ||--o{ "U4ERP.Objects.WorkflowTransactions" : workflow
    "U4ERP.Objects.Customer"  ||--o{ "U4ERP.Objects.RelatedValueOfAttribute" : relatedValues

Explicit Selection

The select property can be used to selectively include properties. This can be done by explicitly referring to some of the fields. We can use the * operator in the expression, which means we are requesting all properties. This is always applied as a local wildcard selection (only applied to the current schema name).

Some examples:

/v1/objects/customers?limit=1&select=*
... returns...
[
    {
        "aliasName": "MARCELI",
        "bankAscriptionName": "",
        "companyId": "EN",
        "companyRegistrationNumber": "",
        "countryCode": "GB",
        "customerGroupId": "X1",
        "customerId": "090909",
        "customerName": "Marceli Gierszon",
        "externalReference": "653615",
        "invoiceCode": "",
        "note": "",
        "objectId": "2c9727aa-ee6f-471c-8cf9-be9e6c67a67e",
        "vatRegistrationNumber": "",
        "workflowState": ""
    }
]

We can use the * wildcard in combination with individual property selection, as shown below, where we use a combination of individually requested properties and a wildcard:

/v1/objects/customers?filter=customerId eq '1010'&filter=contains(customerName, 'Mar')&select=companyId,customerId,customerName,contactPoints(*,address(*),additionalContactInfo(contactPerson))
... returns...
[
    {
        "companyId": "EN",
        "customerId": "1010",
        "customerName": "Hewlett Packard Norway AS",
        "contactPoints": [
            {
                "contactPointType": "1",
                "sequenceNumber": 0,
                "address": {
                    "countryCode": "NO",
                    "place": "OSLO",
                    "postcode": "0212",
                    "province": "",
                    "streetAddress": "Postboks 60, Skøyen"
                },
                "additionalContactInfo": {
                    "contactPerson": "Gunnar Syvertsen"
                }
            }
        ]
    }
]

We can extend a request by selecting optional complex properties, like in the example below, requesting payment(bankAccount):

/v1/objects/customers?filter=customerId eq '10000'&select=companyId,customerId,customerName,payment(bankAccount)
... returns...
[
    {
        "companyId": "EN",
        "customerId": "10000",
        "customerName": "Coffee & Cream Pottery",
        "payment": {
            "bankAccount": "00000000019"
        }
    }
]

Some properties can be extended by using the [T], [C;T] suffix:

[
    {
        "companyId": "EN",
        "customerGroupId": "1",
        "customerGroupId(description)": "Domestic customers",
        "customerId": "1"
    }
]

Please read more about this at Custom annotations: x-u4-describable.