API Reference

Nexus Delta exposes a RESTful interface over HTTP(S) for synchronous communication. The generally adopted transport format is JSON based, specifically JSON-LD. However, other response formats are supported through Content-Negotiation

The API provides access and management of several primary resource types.

Identities

Identities endpoint can be used to fetch user identities.

Operations on identities

Permissions

A permission is the basic unit to provide a way to limit applications’ access to sensitive information.

Operations on permisions

Realms

A realm provides with the necessary information to perform authentication against a certain OIDC provider .

Operations on realms

ACLs

In order to restrict applications’ access to data by placing restrictions on them, three parameters are important:

  • permission: the value used to limit a client (user, group) access to resources.
  • identity: a client identity reference, e.g. a certain user, a group, an anonymous user or someone who is authenticated to a certain realm.
  • path: the location where to apply the restrictions

An ACL defines the set of permissions that certain identities have on a concrete path.

Operations on ACLs

User Permissions

ACLs are the permission model used in Delta. Sometimes it can be more convenient to ask more basic questions about whether a user has a permission, rather than trying to determine this yourself from the ACLs API. This is what the user permissions API is for

Operations on User Permissions

Organizations

The top-level grouping resource in the platform, called organization

Operations on organizations

Projects

The 2nd level grouping resources in the platform, called project. Projects provide isolation of ACLs, resource resolution and indices (ElasticSearch index and Blazegraph namespace).

Operations on projects

Quotas

Defines the maximum number of resources and events that can exist in a certain scope.

Operations on quotas

Schemas

A schema is a resource which defines a set of rules and constrains using SHACL.

Operations on schemas

Resources

A resource is the most generic entity on the Knowledge Graph. Resources can be schemas, resolvers, views, storages, files or data.

Operations on resources

Resolvers

A resolver is a resource which defines the way ids are retrieved inside a project.

Operations on resolvers

Views

A view is a resource which defines the way indexing is applied to certain resources inside a project.

Operations on views

Storages

A storage is a resource which represents a backend where files are stored. It describes where and how files are created and retrieve.

Operations on storages

Files

A file is a binary attachment resource.

Operations on files

Archives

An archive is a collection of resources stored inside an archive file. The archiving format chosen for this purpose is ZIP file.

Operations on archives

Resource Lifecycle

Nexus Delta is build using the event sourcing approach. This strategy captures all changes to an application state as a sequence of events.

All resources in the system generally follow the very same lifecycle, as depicted in the diagram below. Every interaction with an API resource (creation, updates, state changes) is recorded into the system as revisions.

Resource Lifecycle

Data is never removed from the system, but rather is marked as deprecated. Depending on the type of resource, the deprecation flag may have various semantics:

  • Organizations: the resource itself and sub-resources cannot be updated. Views and resolvers contained within this organization will not be considered during indexing and resolution processes.
  • Projects: the resource itself and sub-resources cannot be updated. Views and resolvers contained within this project will not be considered during indexing and resolution processes.
  • Schemas: the resource itself cannot be updated and new data conformant to it cannot be created
  • Resolvers: the resource itself will not be considered during the resolution process
  • Views: the resource itself will not be considered during the indexing process
  • Storages: no new files can be created against the deprecated storage
  • Files: attachments cannot be added/deleted
  • Data: the resource itself cannot be updated

Archives resources are an exception. Those resources are ephemeral. They will be automatically removed from the system after certain time. This time is configurable (config property app.archives.cache-invalidate-after) and it defaults to 5 hours.

Future policies may use this flag to determine if or when the deprecated data may be archived.