Entity API

The Entity API is similar to the Query API but returns complete entities in JSON object format.

Retrieving Data

The URL is also somewhat different. Consider a GET of the following URL:

~api/entity/room/byid/95ad0ad8-0b46-254d-07b9-50f5a845a530

This would return the Room entity given its ID (a GUID). The returned object will look something like this:

{

    Id: “95ad0ad8-0b46-254d-07b9-50f5a845a530”,

    Name: “HOLT 122”,

    Description: null,

    RoomNumber: 122,

    KeyNumber: null,

    PhoneAreaCode: null,

    PhoneNumber: null,

    PhoneExtension: null,

    Width: 20.0,

    Length: 30.0,

    SquareFootage: 600.0,

    MaxOccupancy: 25,

    IsShareable: false,

    MaxSharedActivities: 1,

    PriorityId: null,

    RoomTypeId: null,

    BuildingId: “79D5F153-8695-4679-9819-303D584A01D8”,

    HvacZoneId: null,

    SisKey: “MAIN_HOLT_122”,

    NoSchedule: false,

    ArrangedSection: false,

    DoNotOptimize: false,

    LastSisUpdateDate: null,

    LastImportedDate: null,

    LastExportedDate: null,

    RequiresAttention: false,

    EffectiveStartDate: null,

    EffectiveEndDate: null,

    EffectiveParentId: null,

    IsActive: true,

    WorkflowDefinitionId: null,

    CreatedDate: “2007-03-13T13:11:30Z”,

    CreatedBy: “A394C903-7A6A-400d-936A-0C1142341DEB”,

    ModifiedDate: null,

    ModifiedBy: null,

    RowVersion: 1

}

In the URL, the special token “byid” is used to request an entity given its ID.

The same part of the URL that contained “byid” above is also used to retrieve entities related to a particular entity. For example, to get all rooms for a building:

~api/entity/building/rooms/79D5F153-8695-4679-9819-303D584A01D8

The result of this API call is an array of Room entity objects like the one above. This can also retrieve a one-to-one associated entity in which case the result will be a single object and not an array.

Modifying Data

The Entity API also supports a POST method. This is a non-RESTful API in that all POST requests are sent to the “~api/entity” URL, but this is required to perform a proper database transaction. The general structure of the posted object is as follows:

{

   Room: {

          $: [ // array of complete (current) entities

                 { Id: "2178abfa-689d-49c8-9d1a-426561e3ab6f", Name: "...", ... }

          ],

          "+": [ // array of new entities (inserts)

          ],

          "%": [ // array of modified entities (updates)

          ], 

          "-": [ // array of deleted entity ids

          ], 

          // in this context, associations must be complete and do not support

          // updates (add/remove)

          Regions: { // association name

                 // map keyed by id of "base" entity (Room in this case)

                 "2178abfa-689d-49c8-9d1a-426561e3ab6f": [

                        // array of ids of the members

                        "7a6feb09-34ae-8cf1-737f-86ed721dfeba",

                        "1b1b08ac-ddfd-47a7-a1db-c6e702c0ce3a",

                        "2a6feb09-54af-4cf4-530f-ffed73456eb7",

                        ...

                 ]

          }

   },

   // members of associations must be present in data

   Region: {

          $: [

                 { Id: "7a6feb09-34ae-8cf1-330f-86ed721dfeba", Name: "...", ... }

          ]
   },

   // updates to FK associations are handled as changes to the appropriate

   // entity, but many-to-many association changes are represented as "~associationName"

   "~RoomRegion": {

          "+": [ // array of added 2-tuples (arrays) of [RoomId,RegionId]

                 [ "2178abfa-689d-49c8-9d1a-426561e3ab6f", "1b1b08ac-ddfd-47a7-a1db-c6e702c0ce3a" ]

          ],

          "-": [ // array of removed 2-tuples (arrays) of [RoomId,RegionId]

                 [ "2178abfa-689d-49c8-9d1a-426561e3ab6f", "7a6feb09-34ae-8cf1-737f-86ed721dfeba" ]
          ]
   }
}

Inserts

The “+” object in the POST contains one or more objects per type of entity to be inserted. For example, to insert a Room, you might POST this:

Room: {

        "+": [

                 { Id: "2178abfa-689d-49c8-9d1a-426561e3ab6f", Name: "...", ... }

        ]
}

Since the Astra Database uses GUID’s to identify objects, a properly generated GUID is safe to supply from the client on a new entity.

Updates

Update requests look just like insert requests, except that the supplied objects are generally partial. This is because only the fields that need to be updated are given. All other fields remain unchanged.

Deletes

To delete an entity, you simply put its ID in an array under its type. For example, to delete the above room:

Room: {

        "-": [

                 { Id: "2178abfa-689d-49c8-9d1a-426561e3ab6f" }

        ]
}

Associations

To update many-to-many associations, the desired additions and removals are sent. For example, to add a room (whose Id is “95ad0ad8-0b46-254d-07b9-50f5a845a530”) to one region and remove it from another:

"~RoomRegion": {

          "+": [ // array of added 2-tuples (arrays) of [RoomId,RegionId]

                 [ "95ad0ad8-0b46-254d-07b9-50f5a845a530", "1b1b08ac-ddfd-47a7-a1db-c6e702c0ce3a" ]

          ],

          "-": [ // array of removed 2-tuples (arrays) of [RoomId,RegionId]

                 [ "95ad0ad8-0b46-254d-07b9-50f5a845a530", "7a6feb09-34ae-8cf1-737f-86ed721dfeba" ]

          ]

   }

All modifications specified in the POST are performed as a single database transaction. If the request fails, no modifications will be made to the database. There are often side-effects to updates made via the Entity API, so the total set of modifications to the database may be (much) larger than given in the POST body.