In this document you will learn how to use the Linkurious Enterprise server APIs. Each section describes a new topic along with a code example that can be executed by clicking the button Run code.
During these examples we will send AJAX requests with a helper library called request.
Let's first check if the Linkurious Enterprise server is online. To do so we will use the
GET /api/status API.
This API doesn't require any parameter in input and it is going to respond with a JSON object.
The response will contain a
status.code field that, if everything is working correctly, is set to
While we have been able to check the server and the data-sources status, to use other APIs we need to be authenticated. Linkurious Enterprise supports two forms of authentication:
Here we describe the first form, that you may want to use for the Admin APIs or for opening a visualization. The API endpoint to authenticate via HTTP Cookie is
The HTTP client that we use in this example, request, is going to store a cookie from the first request, and pass it along in the second request,
GET /api/auth/authenticated, that returns an
HTTP 204 only if we are authenticated.
Let's discover which data-sources are available in Linkurious Enterprise. To do so we will use the
GET /api/dataSources API.
The preferred way to use the Linkurious Enterprise APIs is to access them via API key.
First we have to obtain the API key by creating an application. To do so, we will use the
POST /api/admin/applications API.
To use thi API, however, we need to be authenticated as an admin by using HTTP cookie authentication.
When we are authenticated, we can create the application. Applications are used to access a subset of the Linkurious Enterprise APIs on behalf of given groups of users. The administrator can decide which access-rights can be delegated to a given application and for which group of users.
In our example we create an application, that has the right to create, read, update and delete visualizations of any user in the group with id
To know which access right you need for a given API, we refer you to read the Linkurious API documentation.
The response will contain an
apiKey field that you will need to use for API key authentication.
Let's see how to use an API key to access a given resource with an example. We will try to access
GET /graph/schema/nodeTypes/properties API. To do so, we require an API key that has the
For convenience we will use the API key
9010f8661274cb8b1913f970bcd46bdc that already can act on behalf of the user firstname.lastname@example.org.
To authenticate via API key, you need to use HTTP basic access authentication.
So, for example, if your application wants to act on behalf of the user
email@example.com and it uses the API key
AuthenticationHTTP header field to each HTTP request you want to be authenticated
Authenticationfield, you need to provide a string composed by:
In alternative, many libraries, like request, offers facilities to use HTTP basic access authentication:
Here we will learn how to use the Search API to retrieves nodes for which at least one property
matches with the string
Coursera. We will use the
GET /api/:dataSource/search/:type/full API with an API key that has the
Search requests can have a
fuzziness parameter that specify how accurately the search results have to match
the search query. A fuzziness value of
0 means that the search results have to match exactly; instead, using fuzziness
values going towards
1, search results will be more generic but the search request will be more resilient to typos.
Now that we have found the ids of the nodes we are interested about, we can retrieve their properties.
To do so, we will use the
GET /api/:dataSource/graph/nodes/:id API.
We are finally ready to explore the graph. We will use the
POST /api/:dataSource/graph/nodes/expand API.
We will ask Linkurious Enterprise to return the adjacent nodes to the node with ID
47999 and the edges
within this subset of nodes.
In this examples, you will learn how to generate a link to open visualizations within the Linkurious Enterprise user interface.
Let's start with a simple visualization containing only one node of which we know the ID.
To do so, we are going to use the
GET /workspace/new endpoint.
This endpoint is not an API; indeed, we have to be authenticated via HTTP cookie to actually see the visualization.
To learn more about the
GET /workspace/new endpoint, we refer you to read the
GET /api/:dataSource/sandbox API documentation.
The parameters in input to both endpoints are the same. The first endpoint is a link to the Linkurious Enterprise user interface,
the second one is the actual API called behind the scenes.
Similar to the previous example, this time we search for nodes related to
This time to open a visualization we use a Cypher query:
MATCH (n:COMPANY)-[r]-(m) RETURN n, r, m LIMIT 5.
Here we will learn how to create a widget starting from a visualization.
We first use the
POST /api/:dataSource/visualizations API to create a visualization.
Then, we use the
PATCH /api/:dataSource/visualizations API to apply an automatic layout
to the nodes belonging to the newly created visualization.
Finally, with the
POST /api/widget API we publish the visualization as a widget.
Alerts can only be created while authenticated as an admin by using HTTP cookie authentication.
If we want to retrieve the matches generated by an alert, though,
we can use the
GET /api/:dataSource/alerts/:alertId/matches API with the