All Nexus services expose a RESTful interface over HTTP(S) for synchronous communication. The generally adopted transport format is JSON based, specifically JSON-LD.
The services operates on 3 primary types of resources: Organizations, Projects and Resources. Each of them is constrained by a set of SHACL constraints, grouped in what is called a Schema.
- An organization is used to organize and categorize its sub-resources.
- A project is rooted on a given
organization. It is used to organize and categorize its sub-resources while providing a way to interact with them conveniently.
- A resource is rooted on a given
project. In this level of the hierarchy, multiple types of resources can be found. Each of them has a different purpose:
- A schema is a resource that defines a set of constraints using SHACL.
- A resolvers: is a resource that defines the way ids are retrieved inside a project.
- A views: is a resource that describes the way indexing is applied to certain resources inside a project.
- A storage: is a resource which represents a backend where files are stored. It describes where and how files are created and retrieve.
- A file: is a binary resource.
- A archive: is a collection of resources stored inside an archive file. The archiving format chosen for this purpose is tar (or tarball).
Our services are 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.
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 (env. variable
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.