- Migration Topics
- Best Practices
- HIRO Domain Object API
- Receiving updates over websockets
- REST Operations
- HIRO API Overview
- HIRO Audit API
- HIRO Graph - Gremlin Query
- HIRO Graph Action API
- HIRO Graph Auth API
- HIRO Graph List API
- HIRO Graph WebSocket API
- Refresh Token
HIRO Domain Object API
This section describes the Domain Object REST API from the point-of-view of a client of the API.
Scope of the Domain Object API
The Domain Object API enables the client to:
Write and update complex data structures to HIRO DB were they will be mapped to a graph structure (defined by a
viewdefinition). The view is defined in OGIT.
Recieve information on the process of the write transactions (via the
Recieve updates in a complex data structure for ticket data (mapped to
ogit/Automation/AutomationIssueand the related IssueHistory by a
viewdefinition) via the
The Domain Object API exposes the content of the HIRO Graph in terms of high-level domain-specific objects, such as Incident, House, etc, rather than in terms of low-level vertices and edges. In other words, a domain object is a sub-graph of the HIRO graph expressed as a JSON object. Domain objects are identified by an identifier that is guaranteed by the client to be unique on the client’s side. Through this identifier, objects can be created/updated and deleted.
Ongoing writes to domain objects
As writing a domain object (that is, calling
PUT /views/<viewid>/objects/<object-id>) can take a long time, these operations return a transaction. A transaction is a representation of the package of work implied by the operation, e.g., create vertex A, create vertex B, connect A with B through verb C. To get the current status of a transaction do
Updates to domain objects
Updates made to domain objects (made by some other user than the client) are readable at the
/views/<viewid>/updates/<index> end-point on the REST API. This end-point can be read in three different ways. Either by explicitly indexing the update, e.g.,
GET /views/<viewid>/updates/<index>, or using a server-managed iterator, e.g.,
GET /views/<viewid>/updates/?iterator=<iterator-id>, or finally using websockets through the notification meachanism (see below). If the client needs to read updates in a random-access manner, use explicit indexing. If you prefer to read updates in a single bulk, use the iterator interface. Finally, if you wish to minimize latency use the websockets.
A client can create a notification subscription using
POST /views/<viewid>/notifications, which will allow a client to receive notifications when a transaction or domain object has been updated. Outstanding notifications are handled by the server, thus, a client can disconnect and receive any updates occurring while disconnected upon reconnect.