Web-based API

grano exposes most of it’s functionality via a web-based programming interface.The interface communicates mostly using JSON data, and exposes a set of resources, such as projects, schemata, entities, and relations.

Before using this API, it is advisable to read the technical introduction.

Authentication

Read access to all of granos functionality is provided without restriction or the need for authentication. For write operations, such as creating and editing datasets and entities, a user will have to provide either a valid session cookie, generated by using OAuth against GitHub, or an API key. The API key is available in the user profile page for users which have logged in.

The API key must be submitted with each request, and it can either be given as the api_key query parameter, or as the value of the X-Grano-API-Keyrequest header. When an API key is given, grano still performs authorization checks and return an HTTP 401 error when the credentials are invalid, or an HTTP 403 error, when the user tries to modify objects which he is not authorized to write.

Sessions

In order to determine if the (browser-based) user has a valid session, grano provides an API which returns details of the current user. The API is available at:

GET /api/1/sessions

This will contain a flag to indicate a user is logged in, the serialized account data if an account is available, and the user’s API key.

An OAuth-based login can be triggered by pointing the user agent at this endpoint:

GET /api/1/sessions/login

If the query argument next_url is provided, the user is forwarded to the given URL upon completion (successful or not) of the OAuth request.

Inversely, the current session can be erased by visiting this endpoint:

GET /api/1/sessions/logout

The query argument next_url is available and has the same semantics as during login.

Cross-origin requests

All API responses can be encoded as JSON with padding (JSON-P) by adding a callback argument to the request. This will allow remote script inclusion to load data into a web site on a different domain. Cross-origin request sharing (CORS) is not currently supported.

Pagination

All collections of HTTP resources such as datasets or entities provide a similar interface that supports pagination by means of limit and offset. A paginated response will be a JSON object with the following properties:

  • results is an ordered list of the available HTTP resources, often serialized in an abridged (shallow) form to reduce the response size.
  • count gives the overall number of available results, including all available pages.
  • limit and offset give the current state of the pager, indicating the number of results that will be returned with each request and the number of results to be skipped before returning results, respectively.
  • next and previous are two URLs that can be used to retrieve the next or previous page of results. Both properties can be null when either no further pages are available or the query returned the first page of the result set. Both URLs are also returned in the Link headers of the HTTP response.

Any pager can be modified using the following query parameters:

  • limit sets a limit to the number of resources returned. An maximum of 1000 resources is enforced, the default is to return 50 resources if no limit has been provided explicitly.
  • offset instructs the pager to skip the given number of initial records before beginning to return resources.

Domain resources

Grano exposes a set of public (REST) resources via its API. They are listed at the root of the API:

GET /api/1

This root endpoint will also list the current version of grano, as well as a link to the most recent verson of this documentation.

Projects

GET /api/1/projects

Retrieves a collection of all projects that are currently available on grano. Standard pagination arguments are available.

GET /api/1/projects/<slug>

Retrieves a single project from the API, including all its settings.

GET /api/1/projects/<slug>/graph

This endpoint will return a graph representation of the whole project, i.e. a single document that contains all relations and entities in the project in an abbreviated form, unless any filters have been applied.

The following query paramters are available:

  • format can be either json or gexf. The json representation is a custom format for easy integration into visualizations, while gexf is a widely-used exchange format.

Aliases endpoint:

GET /api/1/projects/<slug>/aliases

This endpoint will return a list of names and their aliases for this dataset. That means, for any entity which has only a single assigned name, that name will be exported. If an entity has a single active name but many inactive aliases, each alias is exported as well, with the canonical name given alongside.

This can be used for name-based deduplication in external utilities.

POST /api/1/projects

Operation to create a new dataset. The slug and label properties are required. slug must be a valid url name, i.e. it may not contain non-alphanumeric characters, except the underscore. Optionally, arbitrary metadata can be configured in the settings property, which is a dictionary.

POST /api/1/projects/<slug>

Update an existing project. Most of the fields returned by the GET operation are mutable, except for slug and the automatically generated fields.

DELETE /api/1/projects/<slug>

Delete a project and all related objects, such as entities, relations, schemata and attributes.

DELETE /api/1/projects/<slug>/_truncate

Delete all entities and relations that are part of this project, but leave the project itself, and the schema definitions, intact.

Schemata

For details about the data format, see the schema documentation.

GET /api/1/projects/<slug>/schemata

Retrieves a collection of all schemata that are available in the context of the project identified by slug. Standard pagination arguments are available.

GET /api/1/projects/<slug>/schemata/<name>

Retrieves a single schema from the API, including all attributes.

POST /api/1/projects/<slug>/schemata

Operation to create a new schema. The name and label properties are required. slug must be a valid url name, i.e. it may not contain non-alphanumeric characters, except the underscore. For the complete syntax, see the schema documentation.

POST /api/1/projects/<slug>/schemata/<name>

Update an existing schema. Most of the fields returned by the GET operation are mutable, except for name, project and the automatically generated fields.

Permissions

Permissions connect projects and accounts, granting individual users one or multiple of the following rights: reader, editor, admin. Posessing a more important role automatically implies that less important roles will be granted, too.

GET /api/1/projects/<slug>/permissions

Retrieves a collection of all permissions that are available in the context of the project identified by slug. This collection is only available to administrators of the project. Standard pagination arguments are available.

GET /api/1/projects/<slug>/permissions/<id>

Retrieves a single permission from the API, including all attributes. This resource is only available to administrators of the project or the user affected.

POST /api/1/projects/<slug>/permissions

Operation to create a new permission. The account property is required, and a role such as reader, editor or admin should be set to true. slug must be a valid url name, i.e. it may not contain non-alphanumeric characters, except the underscore.

POST /api/1/projects/<slug>/permissions/<id>

Update an existing permissions. Most of the fields returned by the GET operation are mutable, except for account and project and the automatically generated fields.

DELETE /api/1/projects/<slug>/permissions/<id>

Revoke an existing permissions. This will delete the permission and remove all access rights from the affected user.

Entities

GET /api/1/entities

Retrieves a collection of all entities that are currently available on grano. Standard pagination arguments are available. As a means to filter the results returned by this endpoint, the following arguments can be given as query parameters:

  • project will filter for entities belonging to a specific project, based on the slug provided.
  • property-<name> will filter for entities which have a property <name> and the given value. This will consider active properties only.
  • property-aliases-<name> will filter entities which have a property <name> and one of the historic (i.e. inactive and active) values matches the given value.
  • schema can be used to filter for entities which have a certain schema, indicated by its name. Alternatives can be separated by commata, while multiple values for the query parameters mean that all schemata must be present.
  • q filters results by matching their name property to see if it contains the given parameter.

Autocomplete API:

GET /api/1/entities/_suggest

Auto-suggest API for entity names. Given a prefix, the API will return a set of existing entities whose name starts with the given string, including their name and API URL. Standard pagination arguments are available.

  • q the prefix to be searched, ideally longer than one character.
  • project a project slug to pre-filter the search to only one project.

Get an entity:

GET /api/1/entities/<id>

Retrieves a single entity from the API, including all its properties and references to the schemata that apply.

GET /api/1/entities/<id>/graph

This endpoint will return a graph representation of the entity, including its relations and neighbouts. If requested, this will trigger a recursive process and return a larger subgraph of the entire project.

The following query paramters are available:

  • depth can be a number from 1 to 3 and will set the depth of the recursion, i.e. how many degrees of separation the graph should contain.
  • format can be either json or gexf. The json representation is a custom format for easy integration into visualizations, while gexf is a widely-used exchange format.

Creating entities:

POST /api/1/entities

Operation to create a new entity. The project, schemata and properties fields are required. project must be a reference to a valid project (ie. its slug), while schemata is a list of schemata,identified by their name. properties is expected to be a dictionary, where each key is a property name defined by one of the schemata, and the value is another dict, settings a value and, possibly, a source_url.

POST /api/1/entities/<id>

Update an existing entity. Most of the fields returned by the GET operation are mutable, except for the project, and automatically generated fields.

POST /api/1/entities/_merge

Merge two entities, re-direct relations and copy over properties. The expected payload is two entity references, orig and dest. After the merge, orig will be a pointer towards dest, and dest will have taken on any properties and relations orig had. If both entities have a property, the version on dest is marked active.

DELETE /api/1/entities/<id>

Delete an entity. This will also delete any relations to which this entity is a party.

Relations

GET /api/1/relations

Retrieves a collection of all relations that are currently available on grano. Standard pagination arguments are available. As a means to filter the results returned by this endpoint, the following arguments can be given as query parameters:

  • project will filter for relations belonging to a specific project, based on the slug provided.
  • source and target can be given as an entity id to filter for a specific origin or destination of the relation, respectively.
  • property-<name> will filter for relations which have a property <name> and the given value. This will consider active properties only.
  • schema can be used to filter for relations with a certain schema, indicated by its name. Alternatives can be separated by commata.

Get relations:

GET /api/1/relations/<id>

Retrieves a single relation from the API, including all its properties and references to the schema as well as the source and target entities.

POST /api/1/relations

Operation to create a new relation. The project, source, target, schema and properties fields are required. project must be a reference to a valid project (ie. its slug). source and target are expected to be entity IDs, while schema is a schema, identified by its name. properties is expected to be a dictionary, where each key is a property name defined by the schema, and the value is another dict, settings a value and, possibly, a source_url.

POST /api/1/relations/<id>

Update an existing relation. Most of the fields returned by the GET operation are mutable, except for the project, schema and automatically generated fields.

DELETE /api/1/relations/<id>

Delete a relation.

File uploads

GET /api/1/files

Retrieves a collection of all uploaded files that are currently available on grano. Standard pagination arguments are available. As a means to filter the results, the following arguments can be given as query parameters:

  • project will filter for relations belonging to a specific project, based on the slug provided.

Get a file’s metadata:

GET /api/1/files/<id>

Retrieves a single file’s metadata from the API, including the author, project, file name and mime type.

GET /api/1/files/<id>/_serve

Retrieves a single file’s body, with the appropriate MIME type and file name set in the response headers.

GET /api/1/files/<id>/_table

If the file is CSV data, a JSON tabular representation will be returned that can be used for tabular file previews. If the format is not CSV, this endpoint will yield an error.

  • limit number of rows to be returned. No offset is supported.

Create a new relation:

POST /api/1/relations

Operation to create a new file. The project and file fields are required.

WARNING: Unlike all other endpoints in grano, the submitted content is expected to be multipart/form-data, not application/json. File fileparameter is expected to be a raw file upload.

DELETE /api/1/files/<id>

Delete a file.