Querying data¶

The GET method is used to query information from Lifecycle Twin.

GET method without {id} parameter returns all the resources of the requested type. In the example below, the GET API returns all the Sites (Projects) from the requested Portfolio (Client).

The clientname and authorization HTTP headers are mandatory for all the API requests. Refer Quick Start to generate authorization token.

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

In addition to the mentioned headers, projectid HTTP header is also mandatory while interacting with Site specific resources.

GET /documents

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token>
projectid: <ProjectId>
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Examples¶

Query all sites¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

GET method with {id} parameter returns a specific resource which matches the {id} value.

Get information of a specific site by id¶

GET /clientprojects/2f4978fe-ab1c-4d66-be94-2086d0887a86

Request¶

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Response¶

[
    {
        "Name": "Building1",
        "IsEnabled": false,
        "CreatedOn": "2022-10-18T14:32:17.023Z",
        "Location": {
            "Name": "Zug",
            "ChildrenCount": 0,
            "Id": "4dc758d7-ab1c-4f4b-bd42-fd95c3cd8236"
        },
        "Id": "2f4978fe-ab1c-4d66-be94-2086d0887a86",
        "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00"
    }
]

While querying the data, user can specify field selection, filtering, sorting and pagination using HTTP Headers

Selecting¶

User can specify the list of fields/ properties they would like to include in the response using select HTTP header to improve the performance and reduce the number of data to be transferred.

Some of the fields are returned in the result, regardless if they specified in the select header or not.

The good practice is do not include the fields you don't need for the certain scenario. Especially the referenced fields and collections. On the backend side it generates JOIN query, and in some cases may significantly impact to the performance.

The select header supports fields of the nesting properties as well.

The syntax of the select header is close to the JSON.

{"Field1", "Field2", "Field3": {"Field1OfField3", "Field2OfField3"}}

Use select header in all GET queries

The list of available fields for an entity can be found in the API Reference

In case of specifying an incorrect field, the exception will be thrown.

Example of the request¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Response¶

[
    {
        "Name": "Building1",
        "IsEnabled": false,
        "CreatedOn": "2022-10-18T14:32:17.023Z",
        "Location": {
            "Name": "Zug",
            "ChildrenCount": 0,
            "Id": "4dc758d7-ab1c-4f4b-bd42-fd95c3cd8236"
        },
        "Id": "2f4978fe-ab1c-4d66-be94-2086d0887a86",
        "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00"
    },
    {
        "Name": "Building2",
        "IsEnabled": false,
        "CreatedOn": "2022-10-18T14:32:17.023Z",
        "Location": {
            "Name": "Zurich",
            "ChildrenCount": 0,
            "Id": "4dc758d7-xy1c-4f4b-bd42-fd95c3cd8236"
        },
        "Id": "2f4978fe-xy1c-4d66-be94-2086d0887a86",
        "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00"
    }
]

Filtering¶

User can specify the filter condition to filter the objects using filter HTTP header. It is the powerful mechanism allow user to restrict the query results and find the required information.

Filters are used not only for to search the objects, but also to fetch the related entities. For example, to get the list of components which belong to a room, the /assets endpoint must be used with the filter by room (location)

The following filter clauses are supported:

Usage of proper clause may significantly affect to the performance. Use equals instead of contains may increase the performance up to 10 times. Correct clause based on your use cases.

Simple filter by one property¶

{"clause":{"member":"value"}}

{"equals":{"Name":"ISB-020-000--000_1000319"}}

Simple filter by one property of the referenced field¶

{"clause":{"Property.Field":"value"}}

{"Equals":{"Systems.Id":"b7da56c7-f498-40f7-9104-80ba51cd62ba"}}

Filter by field of the collection property¶

{"clause":{"CollectionProperty[].Field":"value"}}

{"equals":{"ModelObjects[].ObjectId":"41958798-cb80-4c0b-bfaf-63e53192c615-0007b076"}}

Example of the request¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
filter: {"Contains" : {"Name" : "Building1"}}
select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Sorting¶

User can order your data in the response using sort HTTP header.

Syntax¶

{"Property": "OrderType"}

OrderType must be descending or ascending

Example of the request¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
filter: {"Contains" : {"Name" : "Building1"}}
sort: {"Name": "descending"}
select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Pagination¶

User can specify pagination (page number and number of records per page) using the pagination HTTP header

Syntax¶

{"page" : pageNumber, "size" : pageSize}

Example of the request¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
filter: {"Contains" : {"Name" : "Building1"}}
sort: {"Name": "ascending"}
select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}}
Pagination: {"page" : 0, "size" : 20}

The above request will return the first 20 records as response