Linkurious REST API Examples

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.

 Getting started: Get server status

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 200.

request.get({ uri: 'https://crunchbase.linkurio.us/api/status' }, function(err, res) { console.log(res.body); });

 Getting started: User login

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:

• HTTP cookie
• API key (recommended)

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 POST /api/auth/login. 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.

request.post({ uri: 'https://crunchbase.linkurio.us/api/auth/login', body: { usernameOrEmail: 'student@linkurio.us', password: 'student0' } }, function(err, res) { console.log('POST /api/auth/login response:'); console.log(res.body); console.log(''); request.get({ uri: 'https://crunchbase.linkurio.us/api/auth/authenticated' }, function(err, res) { console.log('GET /api/auth/authenticated status code:'); console.log(res.statusCode); console.log(''); request.get({ uri: 'https://crunchbase.linkurio.us/api/auth/logout' }, function(err, res) { console.log('GET /api/auth/logout status code:'); console.log(res.statusCode); }); }); });

 Getting started: Discover data-sources

Let's discover which data-sources are available in Linkurious Enterprise. To do so we will use the GET /api/dataSources API.

request.post({ uri: 'https://crunchbase.linkurio.us/api/auth/login', body: { usernameOrEmail: 'student@linkurio.us', password: 'student0' } }, function(err, res) { request.get({ uri: 'https://crunchbase.linkurio.us/api/dataSources' }, function(err, res) { console.log(res.body); }); });

 Getting started: Obtain an API key

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 4.

To know which access right you need for a given API, please refer to the Linkurious API documentation.

The response will contain an apiKey field that you will need to use for API key authentication.

// we need to be admin to obtain a new API key request.post({ uri: 'https://crunchbase.linkurio.us/api/auth/login', body: { usernameOrEmail: 'admin', password: 'demo_admin' } }, function(err, res) { request.post({ uri: 'https://crunchbase.linkurio.us/api/admin/applications', body: { name: 'demo_app', groups: [11], // we can act on behalf of the group "Server SDK Students". Our student user belongs to this group rights: ["visualization.read", "visualization.create", "visualization.edit", "visualization.delete", "visualization.list", "schema", "graphItem.search", "graphItem.read", "widget.create", "alert.read"] } }, function(err, res) { console.log(res.body); console.log(''); request.get({ uri: 'https://crunchbase.linkurio.us/api/auth/logout' // let's logout too }, function(err, res) {}); }); });

 Getting started: Use the API key

Let's see how to use an API key to access a given resource with an example. We will try to access the GET /graph/schema/nodeTypes/properties API. To do so, we require an API key that has the schema access-right.

For convenience we will use the API key 892d5941dc3da9eeb92f32d71e5e5dc5 that already can act on behalf of the user student@linkurio.us.

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 student@linkurio.us and it uses the API key 892d5941dc3da9eeb92f32d71e5e5dc5:

• Add the Authentication HTTP header field to each HTTP request you want to be authenticated
• As a value of the Authentication field, you need to provide a string composed by:
  • Basic <encodeBase64('<e-mail>:<API_key>')>

request.get({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/graph/schema/node/types', headers: { Authorization: 'Basic ' + btoa('student@linkurio.us:892d5941dc3da9eeb92f32d71e5e5dc5') } }, function(err, res) { console.log(res.body); });

In alternative, many libraries, like request, offers facilities to use HTTP basic access authentication:

request.get({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/graph/schema/node/types', auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' } }, function(err, res) { console.log(res.body); });

 Search: Search for nodes

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 graphItem.search access-right.

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.

request.get({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/search/node/full', auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' }, qs: { q: 'Coursera', fuzziness: 0.7 } }, function(err, res) { console.log(res.body); });

 Search: Get node properties

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.

request.get({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/graph/nodes/47999', auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' }, }, function(err, res) { console.log(res.body); });

 Search: Get node neighborhood

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.

request.post({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/graph/nodes/expand', auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' }, body: { ids: ["47999"] } }, function(err, res) { console.log(res.body); });

 Visualizations: Open with a single node

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.

// we need to be authenticated via HTTP cookie to open a visualization request.post({ uri: 'https://crunchbase.linkurio.us/api/auth/login', body: { usernameOrEmail: 'student@linkurio.us', password: 'student0' } }, function(err, res) { // open a new visualization with one node var nodeId = 47999; console.log('Visualization populated by the node ' + nodeId); var urlSingleNode = 'https://crunchbase.linkurio.us/workspace/new' + '?source=e7900d9b' + '&populate=nodeId' + '&item_id=' + nodeId; console.log('Click here to open it: ' + urlSingleNode); console.log(''); // open a new visualization with one node and its neighborhood console.log('Visualization populated by the node ' + nodeId + ' and its neighborhood'); var urlNodeAndNeighbors = 'https://crunchbase.linkurio.us/workspace/new' + '?source=e7900d9b' + '&populate=expandNodeId' + '&item_id=' + nodeId; console.log('Click here to open it: ' + urlNodeAndNeighbors); });

 Visualizations: Open with a search query

Similar to the previous example, this time we search for nodes related to Coursera.

// we need to be authenticated via HTTP cookie to open a visualization request.post({ uri: 'https://crunchbase.linkurio.us/api/auth/login', body: { usernameOrEmail: 'student@linkurio.us', password: 'student0' } }, function(err, res) { // open a new visualization with a search query var searchQuery = 'Coursera'; var searchFuzziness = 0.7; console.log('Visualization populated by the search query: "' + searchQuery + '"'); var url = 'https://crunchbase.linkurio.us/workspace/new' + '?source=e7900d9b' + '&populate=searchNodes' + '&search_query=' + encodeURIComponent(searchQuery) + '&search_fuzziness=' + searchFuzziness; console.log('Click here to open it: ' + url); });

 Visualizations: Open with a graph query

This time to open a visualization we use a Cypher query: MATCH (n:COMPANY)-[r]-(m) RETURN n, r, m LIMIT 5.

// we need to be authenticated via HTTP cookie to open a visualization request.post({ uri: 'https://crunchbase.linkurio.us/api/auth/login', body: { usernameOrEmail: 'student@linkurio.us', password: 'student0' } }, function(err, res) { // open a new visualization with a graph query var graphQuery = 'MATCH (n:COMPANY)-[r]-(m) RETURN n, r, m LIMIT 5'; var graphDialect = 'cypher'; console.log('Visualization populated by the graph query: "' + graphQuery + '"'); var url = 'https://crunchbase.linkurio.us/workspace/new' + '?source=e7900d9b' + '&populate=pattern' + '&pattern_query=' + encodeURIComponent(graphQuery) + '&pattern_dialect=' + graphDialect; console.log('Click here to open it: ' + url); });

 Widgets: Publish a widget

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.

// first, we expand the node 47999 and we found its neighborhood request.post({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/graph/nodes/expand', auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' }, body: { ids: ["47999"] } }, function(err, expandNodeRes) { // then, we create a visualization containing all the nodes and edges that the previous request returned request.post({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/visualizations', body: { title: 'my visualization', layout: {algorithm: 'force', mode: 'fast'}, nodes: expandNodeRes.body.nodes.map(function(o) { return { id: o.id, data: {geo: {}}, attributes: {layoutable: true, x: 0, y: 0} }; }).concat({ // we also add the node we expanded from id: "47999", data: {geo: {}}, attributes: {layoutable: true, x: 0, y: 0} }), edges: expandNodeRes.body.edges.map(function(o) { return { id: o.id, attributes: {} }; }) }, auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' }, }, function(err, postVisRes) { var visualizationID = postVisRes.body.id; // then, we apply an automatic layout to our visualization (necessary step for creating a widget) request.patch({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/visualizations/' + visualizationID, body: { doLayout: true }, auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' } }, function (err, patchVisRes) { // finally, we create a widget from the visualization request.post({ uri: 'https://crunchbase.linkurio.us/api/widget', body: { visualization_id: visualizationID }, auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' } }, function(err, postWidgetRes) { console.log('Widget populated by the node 47999 and its neighborhood'); var widgetUrl = 'https://crunchbase.linkurio.us/widget/' + postWidgetRes.body; console.log('Click here to open it: ' + widgetUrl); }); }); }); });

 Alerts: Retrieve cases

Alerts can only be created while authenticated as an admin by using HTTP cookie authentication.

If we want to retrieve the cases generated by an alert, though, we can use the GET /api/:dataSource/alerts/:alertId/cases API with the alert.read access-right.

request.get({ uri: 'https://crunchbase.linkurio.us/api/e7900d9b/alerts/1/cases', auth: { user: 'student@linkurio.us', pass: '892d5941dc3da9eeb92f32d71e5e5dc5' }, }, function(err, res) { console.log(res.body); });