10Duke Graph API

The Graph API offers a way to get data into and out of a 10Duke Identity Management REST API and 10Duke Entitlement Management REST API deployment.

The Graph API is an HTTP-based API that applications can use to programmatically query or post data and perform a wide variety of other tasks relating to managing users, groups, and organisations.

Basics

The Graph API is a representation of the information held in a 10Duke Enterprise deployment. It’s an API that models the data in terms of objects and the relationships between them, and allows the client to interact with multiple nodes in a single request.

The Graph API has one endpoint: /graph/

API model

To interact with the Graph API, you use the following key elements:

  • Object

    Individual objects, such as Profile, Organization, or ProfileGroup (a group of related profiles/users).

    Note: On the graph, each object has a unique ID.

  • Relation

    A relation between two objects, indicating relation multiplicity and possibly carrying relation attributes.

  • Operation

    An action taken on a graph object.

Graph selector

This is a relational path to or between an object or a set of objects on the graph. If you want to access data on the graph, you need to construct a graph selector to define and execute your query.

A graph selector can also include conditional expressions limiting the selected object set. You can use parameters to better define or articulate an individual query.

For example, you can specify a date range when requesting a list of all new Profile objects registered in 10Duke Enterprise. Request parameters are specific to each operation you can call on the Graph API.

JSON API

The JSON API is used for standard create, read, update, and delete (CRUD) operations on graph objects and relations, as well as for other higher level operations.

The JSON API maps the HTTP methods POST, GET, PUT, and DELETE to the CRUD operations that are generally available for all objects and relations. You can select other operations by using an operation request parameter.

JSON is used for representing objects and relations returned by reading operations, and for submitting object and relation data to writing operations.

Form API

The Form API is used for creating or updating objects directly from HTML forms.

Object and relation data is given as form input values. The input name is a graph selector describing the item to be created or updated, and the input value gives the value for the item.

Operations vs. HTTP methods

In the context of the Graph API, it’s important to note that an operation is not the same as an HTTP method. There are dozens of operations that can be used to query the Graph API, and only four HTTP methods that are relevant in the same context.

The connection between the two is that if no operation is explicitly specified by giving the “operation” parameter, a default operation is inferred from the HTTP method used as follows:

  • HTTP POST: create

  • HTTP GET: read

  • HTTP PUT: update

  • HTTP DELETE: delete

Relation types

Generally, a graph object can exist in relation to other graph objects with the following relation multiplicities (varieties):

  • One-to-one: An object can be connected to a maximum of one object of another type, and the connected object cannot be connected to other objects of this type.

  • One-to-many: An object can be connected to multiple objects of another type, and the connected objects cannot be connected to other objects of this type.

  • Many-to-one: An object can be connected to a maximum of one object of another type, and the connected object can be connected to multiple objects of this type.

  • Many-to-many: An object can be connected to multiple objects of another type, and the connected object can be connected to multiple objects of this type.

The relation types can be used for building graph, even dynamically. In graph selectors, the relation types are marked with a leading tilde as follows:

  • ~OneToMany

  • ~ManyToOne

  • ~ManyToMany

One-to-one relations must be expressed as one-to-many or many-to-one in graph selectors. ~OnetoOne is not a possible relation type due to limitations of relational databases.

In addition to the standard all-purpose relation objects, many-to-many relations can be extended to contain relation attributes. For example, a Membership relation is a many-to-many relation with attributes for membership validity period.

On this page