EGF2 Graph API

Graph oriented API allows users to operate with objects and edges. An object is an object and an edge is a named connection between a source object and a target object. Example objects: Patient, User, Post, etc. Example edges: User/timeline/Post, Post/comments/Comment, etc.

Relations between objects can be expressed with edges, in this case we have a one-to-many relation from a source to a list of target objects. One-to-one connection is represented with object reference fields. Example: Product.quote, in this case “quote” field on Product object contains an object ID referencing a Quote object. Object reference fields can be specified in graph config, client-api will check that the field contains a valid object reference. Currently client-api only checks that object ID confirms the format and is of a correct object type.

EGF2 generates object IDs automatically when a new object is created. client-data is responsible for generation. Object ID is a string of the following format: “<UUID>-<object type code>”. Object codes are strings and are specified in graph config for each object type. In addition, client-data sets fields “created_at”, “modified_at” and “deleted_at” automatically when it is necessary.

Object Operations

In order to get an object use GET <gateway URL>/v1/graph/<object ID>. I will omit <gateway URL> going forward for brevity sake.

To create an object use POST /v1/graph with JSON body containing object fields. As a result full object JSON will be returned, including field “id”.

To change object use PUT /v1/graph/<object ID> with JSON body containing only the fields that need to be modified. Unchanged fields can be sent as well but it is not required. In order to remove a field from an object completely you need to send “delete_fields”: [“field names”, ...] field inside of the JSON. We don’t support removing fields from within nested structures at the moment.

To delete an object use DELETE /v1/graph/<object ID>.

Edge Operations

To verify existence of an edge please use GET /v1/graph/<src object ID>/<edge name>/<dst object ID>. This request will return edge’s target object in case such an edge exists. 404 will be returned otherwise.

To get a list of objects that belong to an edge use GET /v1/graph/<src object ID>/<edge name>. The list can be paginated with “after”, and “count” query fields. Request will return JSON of the following format:

{
    “results”: [],
    “first”: “<index or object ID of the first entry, int>”,
    “last”: “<index or object ID of the last entry, int>”,
    “count”: <int, total number of objects>
}

Please note that “first” and “last” field values can vary depending on the DB that is used for a deployment. For Cassandra these fields will contain object IDs, for RethinkDB they will contain indices of objects within a collection. We recommend to not try interpreting “first” and “last” field values, just use “last” as a parameter for “after” in case next page should be retrieved. In case the returned page is the last one in the collection field “last” will be omitted.

EGF2 supports expansion on edges for:

  • Other edges, e.g. GET /v1/graph/<Post object ID>?expand=comments will return a list of Post objects. Post objects that have comments will contain Post.comments field populated with a list of related comments along with pagination related info. Only the first page can be retrieved this way. Page size can be specified as follows: GET /v1/graph/<Post object ID>?expand=comments(10) - return 10 objects (if exist). Default page size is 25, max amount of objects that can be specified is 50.
  • Object fields, for example GET /v1/graph/<Post object ID>?expand=user,comments. Post.user field will contain embedded User object.
  • Object fields within nested structures, example: GET /v1/graph/<Post object ID>?expand=foo.bar.

Expansion is also supported on the search endpoint, see next posts for details.

Nested expand up to 4 levels can be used as follows: GET /v1/graph/<Post object ID>?expand=user{roles{favorites}},comments. {} is used to go one level down in expansion for the field on the left of curly braces.

To create a new edge please use POST /v1/graph/<src object ID>/<edge name>/<dst object ID> in case target object already exists, or use POST /v1/graph/<src object ID>/<edge name> with JSON body that contains fields to be used for the new target object. In this case target object and edge will be created simultaneously.

To delete an edge use DELETE /v1/graph/<src object ID>/<edge name>/<dst object ID>.

With this simple set of endpoints we can manipulate data models of any complexity.

See Next - Search with EGF2

comments powered by Disqus