{"componentChunkName":"component---src-templates-default-template-tsx","path":"/documentation/api/api-overview/","result":{"data":{"asciidoc":{"id":"ad680d4f-1ab3-5575-9e9c-59a3329f108d","html":"
\n
Table of Contents
\n\n
\n
\n

Overview

\n
\n
\n

This document will give you an overview about the HIRO Graph, the\ngoverning concepts and the developer API.

\n
\n
\n
\n
\n

REST API

\n
\n
\n
    \n
  1. \n

    All requests(except authenticate) must contain a valid access token. Request a valid access token using /auth/ api.

    \n
    2. \n
  2. \n

    All requests will be made against a base $url (e.g. https://core.engine.datagroup.de/api/).

    \n
    3. \n
  3. \n

    Most of responses are in JSON (to see exception see specific api specs)

    \n
    \n
      \n
    • \n

      JSON response format: set header Accept to application/json

      \n
      • \n
    • \n

      JSON request format (for requests with body): set header Content-Type to application/json

      \n
      • \n
    \n
    \n
    4. \n
  4. \n

    All requests payload unless defined differently in api specification must be utf-8 encoded string.

    \n
    5. \n
\n
\n
\n

API Browser

\n
\n

You can access the HIRO REST API browser on your HIRO instance: https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml.

\n
\n
\n
\n

Error Codes

\n
\n

HIRO Graph uses standard HTTP error codes. Please refer to https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

\n
\n
\n

There might be different error codes, depending on which reverse proxy is configured to be in front of HIRO Graph, please refer to the reverse proxy product documentation you are using.

\n
\n
\n

Error codes with special meaning for HIRO Graph:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Table 1. Table Error Codes
Error CodeDescriptionExplanation

400

Bad Request

please review request against api documentation

401

Token invalid, expired or missing

make sure you use a valid token; get a new token

403

Access denied

access to resource is not granted by current set of policies

404

Not Found

something does not exist

408

Internal request timeout

request took too long; limit request or response size

409

Conflict

e.g. if you try to create an already existing vertex

500

Internal Error

generic error, please contact us at support@hiro.almato.ai

503

Service temporary unavailable

try again later

888

Transaction failure / Upstream error

if two transactions collide, HIRO Graph cannot decide what to do with the failed transaction. Check the condition of the items in the request and retry if still possible

\n
\n

Because everything may fail (software, middleware, network, …​) clients working against the HIRO Graph API are expected to retry failed requests. The expectation, that all requests succeed in the age of the internet is wrong and unrealistic.

\n
\n
\n

A good measure for when to retry is:

\n
\n
\n
\n
if (response.getStatusCode() > 499) {\n  retryTheSameRequest();\n}
\n
\n
\n
\n

All status code in the 4xx range require, that the client fixes something. Be that request format (400), new access token (401) etc pp. The request can e.g. be retried when a new token has been obtained.

\n
\n
\n
\n
\n
\n

Concepts

\n
\n
\n

HIRO Graph is a semantic graph processing platform.

\n
\n
\n

Semantic

\n
\n

HIRO Graph contains Entities (things) with Attributes (properties), Verbs (connections) as well as\nother data like Timeseries or BLOBs.\nThe semantic part is described here https://github.com/arago/OGIT.

\n
\n
\n
\n

Requirements of Namespace, IDs and Attributes

\n
\n\n\n\n\n\n
\n\n\nOne must never depend on the format of the ID that HIRO Graph generates.\n
\n
\n
\n
    \n
  1. \n

    All type ids (attribute ids, entity ids, verb ids) in HIRO Graph are namespaced.

    \n
    2. \n
  2. \n

    To ensure consistency and avoid ambiguity, these have a mandatory prefix http://www.purl.org/.\nEverything after this prefix is the shortened id, that will be by the graph, e.g. ogit/_id derives from http://www.purl.org/ogit/_id. (see http://www.purl.org/docs/index.html for further info). Replace \"/\" in \"_id\" with \"%2F\".

    \n
    3. \n
  3. \n

    Attributes, that are not defined in OGIT have an empty namespace, e.g.: /IssueXML.

    \n
    4. \n
  4. \n

    Free attributes have to begin with \"/\", e.g. \"/environmentType\": \"PROD\",.

    \n
    5. \n
  5. \n

    Free attributes containing dot \".\" are not allowed.

    \n
    6. \n
  6. \n

    All attribute values must be of type string.

    \n
    7. \n
  7. \n

    All attributes are indexed with the keyword analyzer, so wildcards and submatches cannot be used on them, they are also case-sensitive.

    \n
    8. \n
  8. \n

    System attributes start with ogit/_.

    \n
    9. \n
  9. \n

    Changes to system attributes apart of described below are not allowed.

    \n
    10. \n
  10. \n

    ogit/_xid is an external ID which could be set on vertex creation used to map to an external system. Setting this id in a local cache will throw a 409 if another entity has the same ogit/_xid. Nevertheless multiple entities with the same ogit/_xid may exist at the same time if data is created with sync.

    \n
    11. \n
  11. \n

    ogit/_content when written is indexed with the standard analyzer. It is also indexed with an ngram analyzer. a text like \"a sample text of things\" can be queried like ogit/_content:sample to find words in it, or ogit/_content.ngram:amp to find ngrams in it. This field is allowed for all entities and can be filled automatically by setting the indexed: property in the entity definition.

    \n
    12. \n
  12. \n

    ogit/_content is the sum of all attribute values that are specified in OGIT under ogit:indexed-attributes in OGIT. e.g. https://github.com/arago/OGIT/blob/master/NTO/Automation/entities/MARSNode.ttl#L131

    \n
    13. \n
  13. \n

    ogit/_tags when written is indexed as a list of keywords. The format when writing is \"some, tag, with spaces\" and internally is indexed as [\"some\", \"tag\", \"with spaces\"]. It can be searched like ogit/_tags:some to find full tags in the list. This field is allowed for all entities.

    \n
    14. \n
  14. \n

    ogit/_owner could be set to team id to allow sharing data by policies. if not set in request default team from account profile (in case not set default for organization) would be used

    \n
    15. \n
  15. \n

    ogit/_scope could be set on vertex creation to put vertex in specific data scope, if not default from context would be used

    \n
    16. \n
  16. \n

    The length of attribute values must not exceed 60kB. If they are larger than 60kB, they will not be indexed. The following attributes can have an arbitrary content length, but can not be used to match in queries:

    \n
    \n
      \n
    • \n

      ogit/message

      \n
      • \n
    • \n

      ogit/content

      \n
      • \n
    • \n

      ogit/description

      \n
      • \n
    • \n

      ogit/comment

      \n
      • \n
    • \n

      ogit/licenseKey

      \n
      • \n
    • \n

      ogit/question

      \n
      • \n
    • \n

      ogit/response

      \n
      • \n
    • \n

      ogit/reason

      \n
      • \n
    • \n

      ogit/serviceContract

      \n
      • \n
    • \n

      ogit/taskLog

      \n
      • \n
    • \n

      ogit/value

      \n
      • \n
    • \n

      ogit/values

      \n
      • \n
    \n
    \n
    17. \n
  17. \n

    Free attributes can have any length but cannot be used in queries if over 60kB.

    \n
    18. \n
  18. \n

    Limitations on data size (trying to create or update data bigger than allowed would end up with 400 error). For performance reasons it is recommended to build applications in the way that single data piece is not bigger than 1MB.

    \n
    \n
      \n
    • \n

      issue/task in engine - 1MB

      \n
      • \n
    • \n

      vertex - 10MB

      \n
      • \n
    • \n

      timeseries value - 100MB

      \n
      • \n
    • \n

      BLOB content - 100MB

      \n
      • \n
    • \n

      api request payload 100MB

      \n
      • \n
    \n
    \n
    19. \n
  19. \n

    Stream responses are used to transfer possibly bigger amount of data pieces like query or timeseries values response. each item it send from server separately and could be parsed by json streaming. e. g. {\"items\":[{$data1},{$data2},…​,{\"error\":{\"code\":408,\"messge\":\"internal request timeout\"}}]}. Note: client shall check if data piece contain `\"error\"`and handle it (after \"error\" no more data would be send)

    \n
    20. \n
\n
\n
\n
\n
","document":{"main":"HIRO API Overview","title":"HIRO API Overview","subtitle":""},"fields":{"toc":true,"location":["documentation","api","api-overview"]}},"sidebarYaml":{"id":"6d066bdd-c982-5a69-b909-a31e6fc044e0","showIndex":null}},"pageContext":{"id":"ad680d4f-1ab3-5575-9e9c-59a3329f108d","parent":"documentation"}},"staticQueryHashes":["1010459453","1010459453","2356112386","2356112386","2603905930","2603905930","3026652197","3026652197","3167850324","3167850324","63159454","63159454"]}