API
This article gives an overview of the fylr API. The API specification is available in OpenAPI format and can be individually generated by your own fylr instance.
The API documentation is work in progress! Please refer to the easydb 5 predecessor for this API, most of the API is the same in easydb 5 and fylr.
Endpoints
fylr uses powerful endpoints to allow storage and retrieval of data objects. The schema for these objects is freely and highly configurable, much like using an SQL database system in which you can freely define your schema to store your data.
Configuration & setup
Most of the fylr configuration is offered via API. This includes general system configuration such as a custom logo, custom colors, the name of the system, email server configuration, LDAP & SAML IDP configuration etc.
This endpoint is used to define the basic structure of how objects are stored in fylr. This is the main endpoint which created the data model.
On top of the data model, fylr knows the notion of masks. Masks are used to hide, show and configure columns in various views of the application. Mask are also the basis to allow users access to data.
For frontend to display error message and other system output localised, fylr provided the translation keys for various languages. This endpoint is also used to save and load custom localisation for schema and mask.
fylr is extensible by plugins. The plugin endpoint is used to manage plugins.
Retrieve a basic set of information about the running fylr instance.
The endpoint is used to manage storage location, create backups, purge the system and other system related actions.
Base types
Base types are used to setup the basic types to drive the system.
This endpoint manages the users stored in fylr.
Groups are used to group users. Users can be in multiple groups. This is equivilant to roles in other systems.
The endpoint manages the preset for permissions. It also lets frontends retrieve a list of available permission settings.
One important type is the pool. Pools allow you to categorize objects. It is often use to reflect the departments of an organisation. Pools can be used as the top level object of the permission management for objects. Pools are hierarchically structured.
The schema of fylr defines the object types. Each object is stored in the format of an object type. This endpoint is used to configure the behaviour of each object types including permission management.
Frontend and server can use messages to be presented to the user. The server message type is used to let users confirm an EULA or other informations right after login.
fylr has an event system where most of the server activity will be logged in. Events are meant for administrator and users. The logfile of fylr targets the system administrator who needs a closer relation to the platform where fylr is running on. Applications can also use the event system and post their own custom events.
Tags can be assigned to objects to drive permission management, search filters and transitions.
Transitions are used to define actions which run when objects change their states. Such actions can include email notifications or tags settings.
Users can collect and share objects in collections. These collections are stored in a base type managed by fylr. Collections are hierarchically structured.
This endpoint is used to record publishing information about objects in other systems than fylr.
This endpoint is used to store mappings for im- and export of mostly XML based data, such as image metadata.
Save, load and find objects
This endpoint is used as a pre-flight call for frontends to display available choices to users to switch pools or tags of objects.
This endpoint is used to save and load objects. It accesses the database directly without the use of the indexer. Every fylr instance has different properties in this endpoint.
The endpoint to manage files. Features include upload and downlaod of originals as well as renditions. This enpoint also offers IIIF image tiles.
Every object in fylr is compiled into an index document and send to Opensearch or Elasticsearch for fast retrieval. The endpoint acts as a proxy to the indexer in order to find objects.
To offer autocompletion to the user, fylr offers the suggest endpoint.
Export definitions can be created by users to export object data. Exports are based on a stored search and can be repeadetly executed (even scheduled). Export formats include XML, CSV and JSON.
OAI/PMH is a standard to harvest data from object storage systems such as fylr.
The endpoint is used to retrieve data from a specific object. The object can be accessed using various means, like _uuid, _id or unique column retrieval. Also available on this endpoints are IIIF manifests and binary file data.
The webdav endpoint allows to save and load files stored in fylr.
OpenAPI format
The API documentation is available in Open API 3.1.0 format. Most endpoints act the same across different instances of fylr. However, a few endpoints depend on the configurable schema of each fylr. These endpoints adapt themselves to the schema:
/api/db: The endpoint to synchronously add and retrieve object data.
/api/search: This endpoint accesses the indexed data for search and aggregations. The returned data is retrieved from the database. The data is indexed asynchronously, so there can be a slight time gap between the update of an object and when its data lands in the index document.
Because of the variable nature of the fylr API, every fylr instance can output it's own specific Open API specification. Use /inspect/apidocs to browse the Open API documentation. The specification can found under /inspect/apidocs/spec/spec.json.
Last updated