CRUD IoT Objects with OData API

In this article

    Show more
    Show less

    1. Introduction

    This article shows how to read, create, edit, and delete IoT objects exposed by Immersive RestFrontage: Equipment, EquipmentInstance and SupervisionScope. These four operations make up the CRUD. He also describes the management of their association, represented by SupervisionScopeEquipmentInstance.

    The journey always begins with the search for theOrganization concerned. Its identifier then makes it possible to select the right resources and to check their ownership before each entry. We will take the example of a temperature sensor attached to a building.

    2. Understanding Objects

    Purpose Role Main relationship
    Organization Organization that owns the data. Sound Identifier defines the scope of the processing.
    Equipment IoT equipment family. She wears OrganizationIdentifier and can have multiple instances.
    EquipmentInstance Actual equipment installed or tracked. It belongs to a family via ParentEquipmentIdentifier. Its organization is that of this family.
    SupervisionScope Scope of supervision, attached to an organization. A perimeter can contain multiple instances, and an instance can be associated with multiple scopes.
    SupervisionScopeEquipmentInstance Association between a perimeter and an instance. Its key is composed of SupervisionScopeIdentifier and EquipmentInstanceIdentifier.

    Equipment describes the model of the equipment, while EquipmentInstance designates a concrete object. To attach an instance to a perimeter, the association is created; the creation of the perimeter or instance does not automatically create this link.

    An object Equipment will be for example Elevator, Temperature sensor, Automatic door, Emergency vehicle, ...

    An object EquipmentInstance will be for example Elevator ATR5910, Level 0 temperature sensor hall, Automatic dock door, X312A Emergency Vehicle, ... Via the relationship ParentIdentifier We can link a parenthood between equipment instances. For example, an electrical cabinet could have circuit breakers, automatons, etc. as a child. An object EquipmentInstance necessarily has a property ParentEquipmentIdentifier pointing to a Equipment existing.

    An object SupervisionScope will be for example IOT Level 4 Gear, Administrative Building, Raincourt station, ...

    SupervisionScopeEquipmentInstance necessarily has the properties SupervisionScopeIdentifier and EquipmentInstanceIdentifier pointing to existing objects.

    The following diagram defines the relationship between the different objects:

    flowchart TD
        O["Organization"] -->|"OrganizationIdentifier"| E["Equipment : famille"]
        E -->|"ParentEquipmentIdentifier"| I["EquipmentInstance : objet concret"]
        O -->|"OrganizationIdentifier"| S["SupervisionScope : périmètre"]
        S -->|"SupervisionScopeIdentifier"| L["SupervisionScopeEquipmentInstance"]
        I -->|"EquipmentInstanceIdentifier"| L
    

    3. Preparing for calls

    3.1 Authentication

    The examples use a Bearer token. Pass the header Authorization on each request, including when the sample reads only show the URL.

    For API key-authenticated integration, replace this header with the following two headers, on each call:

    x-app-name: {{appName}}
    x-api-key: {{apiKey}}
    
    

    Direct API key access does not require prior login or conversion to a client-side Bearer token. The account associated with the key remains subject to organization access and business permissions. Keep the key in the secure configuration of the calling application; do not insert it into JavaScript distributed to the browser.

    3.2 Query template and format

    The OData API is exposed under /odata. Check out their template before onboarding a client to check all the properties and their types:

    GET {{server}}/odata/$metadata
    Authorization: Bearer {{token}}
    Accept: application/xml
    
    

    Writes use JSON. The token must be associated with an account that is authorized to read or modify the requested data.

    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    

    In the URLs in this article, filter spaces are left readable. The HTTP client must encode the request parameters. In an OData string, an apostrophe is doubled: Name eq 'L''Atelier'.

    4. Finding the organization before any IoT operation

    4.1 Find the target organization

    Start by looking for the organization that is accessible to the account you're using, without assuming its identifier:

    GET {{server}}/odata/Organizations?$filter=Name eq 'Organisation Demo'&$select=Identifier,Name,DistinguishedName&$top=2
    Authorization: Bearer {{token}}
    Accept: application/json
    
    

    Illustrative excerpt of answer, without OData annotations:

    {
      "value": [
        {
          "Identifier": 7,
          "Name": "Organisation Demo",
          "DistinguishedName": "OU=Organisation Demo,DC=exemple,DC=fr"
        }
      ]
    }
    
    

    The results of a collection read can be found in the table value. Explicitly address these three situations:

    • No results : Stop processing. The organization may be absent or inaccessible to the account being used.
    • A result : check that it matches the expected organization, then keep its Identifier.
    • Multiple results : specify the selection, for example using the DistinguishedName expected. Do not arbitrarily choose the first result.

    The limit $top=2 is sufficient to detect ambiguity. It is not used to choose an organization.

    If a credential is already provided by your integration configuration, check its existence, accessibility, and identity:

    GET {{server}}/odata/Organizations(7)?$select=Identifier,Name,DistinguishedName
    
    

    In the sequel, 7 represents the identifier actually found. IDs 12, 34, and 56 will represent a family, instance, and scope, respectively, found or created during processing.

    4.2 Maintaining a consistent scope

    Resource Organization Membership Filter 7 Attachment to the creation
    Equipment OrganizationIdentifier eq 7 "OrganizationIdentifier": 7
    EquipmentInstance ParentEquipment/OrganizationIdentifier eq 7 ParentEquipmentIdentifier must designate a family of the organization 7.
    SupervisionScope OrganizationIdentifier eq 7 "OrganizationIdentifier": 7
    Association Check the instance and scope. Use both controlled credentials.

    Perform this resolution at the beginning of each business run, and then reuse the confirmed ID for the operations that make up that business. Repeat if the target server, account, or organization changes.

    For Bearer calls, you can also declare the organization context with this optional header, once the organization is found:

    X-Organization-Identifier: 7
    
    

    5. Read Organization Objects

    5.1 List and filter

    GET {{server}}/odata/Equipments?$filter=OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier&$orderby=Identifier&$top=100
    
    
    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7&$select=Identifier,Name,ParentEquipmentIdentifier&$orderby=Identifier&$top=100
    
    
    GET {{server}}/odata/SupervisionScopes?$filter=OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier&$orderby=Identifier&$top=100
    
    

    To limit the reading to family 12 instances, also keep the organization filter:

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and ParentEquipmentIdentifier eq 12&$select=Identifier,Name,ParentEquipmentIdentifier&$orderby=Identifier&$top=100
    
    

    The filter tracks a relationship with /. It is not necessary to add $expand to filter on a parent property.

    OData options for selecting, expanding, filtering, sorting, and paginating are available. $top is limited to 200; this does not mean that all collections are automatically paginated in blocks of 200. For the second page of 100 items, use for example $orderby=Identifier&$top=100&$skip=100. If the response provides @odata.nextLink, follow this link.

    5.2 Find a business object

    Search for a family by name within the organization:

    GET {{server}}/odata/Equipments?$filter=OrganizationIdentifier eq 7 and Name eq 'Capteur de température'&$select=Identifier,Name,OrganizationIdentifier&$top=2
    
    

    For an instance, you can search for its name or an external reference:

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and InteroperabilityReference eq 'GTB-TEMP-001'&$select=Identifier,Name,ParentEquipmentIdentifier&$top=2
    
    

    Require a unique result before reusing its identifier. Don't assume that an external reference is unique without verifying the results. If there are no results, create a new object only if that creation is part of the expected processing.

    5.3 Check a target before editing or deleting

    For a target with a known ID, combine that ID with the organization filter:

    GET {{server}}/odata/Equipments?$filter=Identifier eq 12 and OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier
    
    
    GET {{server}}/odata/EquipmentInstances?$filter=Identifier eq 34 and ParentEquipment/OrganizationIdentifier eq 7&$select=Identifier,Name,ParentEquipmentIdentifier&$expand=ParentEquipment($select=Identifier,OrganizationIdentifier)
    
    
    GET {{server}}/odata/SupervisionScopes?$filter=Identifier eq 56 and OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier
    
    

    Each query must find exactly one object. If value is empty, stop the operation: Do not remove the organization filter to find an alternative target.

    5.4 Read the relationships

    GET {{server}}/odata/EquipmentInstances(34)/ParentEquipment
    GET {{server}}/odata/EquipmentInstances(34)/SupervisionScopes
    GET {{server}}/odata/SupervisionScopes(56)/EquipmentInstances
    
    

    Use these routes after you have checked the membership of the starting object. They allow you to find the family of an instance and to consult the associated objects. A collection can be empty.

    To keep the organization filter on objects returned by associations:

    GET {{server}}/odata/SupervisionScopes(56)/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7&$select=Identifier,Name,ParentEquipmentIdentifier
    
    
    GET {{server}}/odata/EquipmentInstances(34)/SupervisionScopes?$filter=OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier
    
    

    6. Create the objects

    After having rediscovered the organization, a creation is done with POST on the collection. Do not provide Identifier For the three main objects: the identifier is assigned by the server. The bodies below show the properties useful to the scenario; $metadata Describes the contract for the deployed version.

    6.1 Create a family of equipment

    POST {{server}}/odata/Equipments
    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    {
      "Name": "Capteur de température",
      "OrganizationIdentifier": 7,
      "IsEnabled": true
    }
    
    

    In case of successful creation, the answer is 201 Created. Keep theIdentifier returned: It will be needed to create instances of this family. We will assume that it is 12. The server can return 409 Conflict if it detects a duplicate name.

    6.2 Create an instance

    First, verify that family 12 belongs to Organization 7 with the previous control query.

    POST {{server}}/odata/EquipmentInstances
    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    {
      "Name": "CAPT-001",
      "ParentEquipmentIdentifier": 12,
      "Location": "Bâtiment A - Local technique",
      "InteroperabilityReference": "GTB-TEMP-001",
      "IsEnabled": true
    }
    
    

    ParentEquipmentIdentifier Reference the family Equipment and thus determines the organization of the body. InteroperabilityReference is an optional reference to an external system. It does not replace the OData identifier. Keep theIdentifier of the answer, 34 in the continuation of the example.

    6.3 Create a monitoring perimeter

    POST {{server}}/odata/SupervisionScopes
    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    {
      "Name": "Bâtiment A",
      "OrganizationIdentifier": 7,
      "IsEnabled": true
    }
    
    

    Use the organization that was actually found at the beginning of the treatment. Save theIdentifier of the response, 56 in our example, and then create associations. A duplicate name detected by the server results in a conflict.

    7. Edit Objects

    Use PATCH on the identified resource to change only the properties indicated. Properties that are not present in the body are preserved. At the beginning of processing, find the organization; before each write, check the target with its identifier and the membership filter presented above.

    PATCH {{server}}/odata/Equipments(12)
    Authorization: Bearer {{token}}
    Content-Type: application/json
    
    {
      "Name": "Capteur thermique"
    }
    
    

    Example of changing the name of an instance:

    PATCH {{server}}/odata/EquipmentInstances(34)
    Authorization: Bearer {{token}}
    Content-Type: application/json
    
    {
      "Name": "CAPT-001-EST"
    }
    
    

    Example of a change in the scope:

    PATCH {{server}}/odata/SupervisionScopes(56)
    Authorization: Bearer {{token}}
    Content-Type: application/json
    
    {
      "Description": "Supervision du bâtiment A et de ses locaux techniques",
      "IsEnabled": true
    }
    
    

    After each update, replay the resource with its organization filter to check the saved values. An empty name is rejected when a change is made, and a duplicate name detected causes a conflict.

    7.1 Hierarchy and organizational change

    ParentIdentifier defines a parent of the same type: another instance for a EquipmentInstance, another perimeter for a SupervisionScope. Also check the organization of the intended parent. To remove this optional attachment, send "ParentIdentifier": null. Hierarchy controls reject changes that create a circular reference.

    Change ParentEquipmentIdentifier Reassigns an instance to another family and can change its effective organization. Change OrganizationIdentifier on a family can affect all of its instances. These operations require rechecking objects and their associations; they are not required to change a name or description.

    The API also exposes PUT, which follows an override logic. For targeted changes to this article, use PATCH so that you don't unintentionally reset omitted properties to their default values.

    8. Associate an instance with a perimeter

    First find the organization and check both ends with the control queries for instance 34 and perimeter 56. For this journey, both must belong to organization 7.

    The relationship is a resource in its own right. It does not have an organization field to provide. Create it with POST on SupervisionScopeEquipmentInstances :

    POST {{server}}/odata/SupervisionScopeEquipmentInstances
    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    {
      "SupervisionScopeIdentifier": 56,
      "EquipmentInstanceIdentifier": 34
    }
    
    

    The two identifiers form the key to the association. There is noIdentifier to retrieve. The same link cannot be created twice; a second creation returns 409 Conflict.

    After checking both ends, the association can be read directly:

    GET {{server}}/odata/SupervisionScopeEquipmentInstances(SupervisionScopeIdentifier=56,EquipmentInstanceIdentifier=34)
    
    

    To remove only the link between instance 34 and perimeter 56, re-control both objects in the target org, and then call:

    DELETE {{server}}/odata/SupervisionScopeEquipmentInstances(SupervisionScopeIdentifier=56,EquipmentInstanceIdentifier=34)
    Authorization: Bearer {{token}}
    
    

    An alternate deletion route is available from the instance:

    DELETE {{server}}/odata/EquipmentInstances(34)/SupervisionScopes(56)
    Authorization: Bearer {{token}}
    
    

    Removing this association does not delete the instance or scope. To change the scope of attachment, remove the link and then create a new association with the previously verified scope.

    9. Delete an object

    Find the organization, check the target's membership, and address its dependencies before using DELETE. To clean up the objects created in the example, first remove the association, and then remove the instance:

    DELETE {{server}}/odata/EquipmentInstances(34)
    Authorization: Bearer {{token}}
    
    

    The family can be deleted after checking that no other instance or dependency references it:

    DELETE {{server}}/odata/Equipments(12)
    Authorization: Bearer {{token}}
    
    

    The perimeter may be deleted after treatment of his other associations, his possible children and his other dependencies:

    DELETE {{server}}/odata/SupervisionScopes(56)
    Authorization: Bearer {{token}}
    
    

    10. Answers and errors to be addressed

    Answer Common interpretation
    200 OK Read or update successfully, with representation of the resource by operation.
    201 Created Resource created; read the identifier in the returned representation or header Location.
    204 No Content Successful operation without a body; deletions expected to return. An update may also not return a representation.
    value: [] There are no visible objects that match the filter. Stop writing that depends on this search.
    400 Bad Request Invalid body, organization reference that does not exist when creating a scope, empty name, or circular hierarchy.
    401 Unauthorized / 403 Forbidden Absent/invalid authentication or insufficient authorization. An unreachable organization or dependency can also lead to a denial.
    404 Not Found Resource or association requested not found.
    409 Conflict Name already used or association already present.

    The exact answers may vary depending on the type of operation and API version. The client must check the HTTP status, the number of results, and the values returned, and then retain the error body to view or log the detail returned by the server. Read and write permissions may differ: reading an object does not guarantee the right to modify it.

    11. Full career summary

    1. Authenticate yourself and find theOrganization target.
    2. To keep your username for processing operations.
    3. Read or create a family Equipment in this organization.
    4. Read or create a EquipmentInstance with the identifier of this family.
    5. Read or create a SupervisionScope in the same organization.
    6. Control both ends, then create their association.
    7. Before any changes or deletions, verify that the targets are members of the organization.
    8. Replay data after writes; delete associations and objects separately as needed.

    The organization defines the scope of work; identifiers denote the resources used during processing. Keep these two pieces of information together to avoid mixing data from multiple organizations.