• Services
  • Migration Topics
  • Integration
  • Concepts
  • Best Practices
  • Api
    • DomainObjectApi
      • RestCalls
      • HIRO Domain Object API
      • Receiving updates over websockets
      • REST Operations
    • Changelog
    • 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

Overview

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

DoapiConcept Ticket
DoapiConcept Model

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 view definition). The view is defined in OGIT.

  • Recieve information on the process of the write transactions (via the transactions endpoint).

  • Recieve updates in a complex data structure for ticket data (mapped to ogit/Automation/AutomationIssue and the related IssueHistory by a view definition) via the updates endpoint.

Domain Objects

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 GET /views/<viewid>/transaction/<transaction-id>.

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.

Notifications

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.