Actinia Basics
Actinia REST API documentation
Actinia is fully documented using the OpenAPI standard^1, better known as swagger^2. The JSON definition of the API can be accessed here:
https://actinia.mundialis.de/latest/swagger.json
A nicely rendered ReDoc version is available here:
https://redocly.github.io/redoc/?url=https://actinia.mundialis.de/latest/swagger.json
To generate a readable documentation out of the swagger.json file, the spectacle tool can be used:
# Download the latest swagger definition from the actinia service
wget https://actinia.mundialis.de/latest/swagger.json -O /tmp/actinia.json
# Run spectacle docker image to generate the HTML documentation
docker run -v /tmp:/tmp -t sourcey/spectacle spectacle /tmp/actinia.json -t /tmp
# Start Firefox to show the documentation
firefox /tmp/index.html
The petstore swagger UI creator^3 can be used to show all available REST API calls and all response models in a convenient way.
User, user-roles and user-groups
Actinia uses the concept of users, user-roles and user-groups to manage the access to the actinia databases and API calls. A single user has always a specific user role and can be member of one single user-group.
The following user-roles are supported:
1. superadmin
- Can create, modify and delete users with all user-roles
- Has access to all API calls and read/write access to all databases
2. admin
- Can access all API calls
- Can create, modify and delete users with the maximum user-role user of the same user group
- Has access to persistent databases that were granted by a superadmin
3. user
- Can run computational tasks in ephemeral and user specific databases
- Can create, modify and delete locations in a user specific database
- Can create, modify and delete mapsets in user specific databases
- Has limited access to API calls
- Can not create, modify or delete users
- Has access to persistent databases that were granted by a superadmin
4. guest
- Has very limited access to API calls
- Can not create, modify or delete mapsets
- Can not create, modify or delete users
- Has access to persistent databases that were granted by a superadmin
Overview table:
| task | superadmin | admin | user | guest | notes |
|---|---|---|---|---|---|
| amount raster cells is unlimited | y | y | limited, selected via redis | limited, selected via redis | - |
| database access is unlimited | y | only to persistent databases that were granted by a superadmin | limited, defined in redis | limited, defined in redis | - |
| location/mapset access is unlimited | y | y | can create, modify and delete locations/mapsets in user specific databases, defined in redis | has access to persistent databases that were granted by a superadmin, defined in redis | - |
| module access is unlimited | y | y | can run computational tasks in ephemeral and user specific databases | has very limited access to API calls | - |
| get, create, delete a single user | y | users with the maximum user-role user of the same user group | n | n | Only normal users (role=user can be created) |
In the file actinia.cfg, limits and more can be defined:
[LIMITS]
max_cell_limit = 2000000
process_time_limt = 60
process_num_limit = 20
number_of_workers = 3
The Actinia databases
Actinia manages GRASS GIS locations in its persistent database. User are not permitted to modify data in the actinia persistent database, but can access all data read-only for processing and visualization. Data in the persistent database can only be accessed via HTTP GET API calls.
The user can either process data in an ephemeral databases, that will be removed after the processing is finished, or in a user specific database. A user specific database is persistent, only visible to users of the same user-group and can contain any data the user has imported. The user can read-access all data from the persistent database while running analysis in the ephemeral database or user specific database.
Summary
1. Persistent database
- Read only database with locations and mapsets that can be used as processing environment and data source
- Data can only be accessed using HTTP GET API calls
2. Ephemeral database
- All processing is performed in ephemeral databases for performance and security reasons
- Ephemeral databases are created for all API calls and removed after the processing is finished
- Ephemeral databases use persistent databases as processing environments to access required data from mapsets in persistent locations
3. User specific databases
- Persistent databases that can be created and modified by a specific user group
- The base for a location in a user specific database can be a location from a persistent database, however mapsets names must be unique.
- A user group can only access a single database with any number of locations
Footnotes