API docs by Redocly

EvoNEST API (1.1.0)

Download OpenAPI specification:Download

Daniele Liprandi: daniele.liprandi@gmail.com URL: https://github.com/daniele-liprandi/EvoNEST-backbone License: GNU Affero General Public License v3.0

EvoNEST General Documentation

The EvoNEST User Guide and the EvoNEST Developer Guide are found here: https://daniele-liprandi.github.io/EvoNEST-backbone/

EvoNEST API Documentation

The EvoNEST API allows users to interact with the MongoDB databases generated in their NEST, plus it gives access to utility functions useful in ecological, evolutionary and biological research.

Features

  • Samples Management: Create, update, and retrieve biological samples with taxonomic information
  • Traits Measurement: Record and analyze trait measurements with statistical calculations
  • Experiments: Manage measurements, documents and raw data
  • File Storage: Upload and manage research files with metadata
  • User Management: Handle user accounts and permissions
  • Utilities: Geocoding, species image search, and data processing tools

Authentication

Most endpoints require proper authentication and database access permissions.

Data Format

All endpoints return JSON data unless otherwise specified. Dates are in ISO 8601 format.

Users

User account management and authentication

Retrieve all users

Get a list of all users in the system. When not in auth mode, filters users by database access based on the current user's permissions.

Authorizations:
bearerAuthsessionAuth
query Parameters
auth
boolean

Set to true to bypass database filtering (for authentication flows)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create, update, or modify a user

Handles multiple user operations based on the method field:

  • create: Create a new user account
  • update: Update an existing user's information
  • setfield: Update a specific field of a user
  • delete: Remove a user from the system
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
required
string
Value: "create"

Action to perform

name
required
string

User's full name

email
required
string <email>

User's email address

institution
string

User's affiliated institution

role
string
Enum: "admin" "researcher" "student" "viewer"

User's role in the system

databases
Array of strings

List of databases the user should have access to

Responses

Request samples

Content type
application/json
Example
{
  • "method": "create",
  • "name": "Dr. Jane Smith",
  • "email": "jane.smith@university.edu",
  • "institution": "University of Science",
  • "role": "researcher",
  • "databases": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "User updated successfully",
  • "id": "507f1f77bcf86cd799439011"
}

Get current user information

Retrieves the current authenticated user's profile information from the database

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "name": "John Doe",
  • "email": "john.doe@example.com",
  • "institution": "University of Science",
  • "role": "researcher",
  • "databases": [
    ],
  • "activeDatabase": "spiderdb",
  • "isActive": true,
  • "createdDate": "2024-01-15T10:30:00Z",
  • "recentChangeDate": "2024-03-15T10:30:00Z",
  • "logbook": [
    ],
  • "auth0id": "auth0|507f1f77bcf86cd799439011"
}

Update user information

Updates specific fields in the current authenticated user's profile

Authorizations:
sessionAuth
Request Body schema: application/json
method
required
string
Value: "setfield"

Update method

id
string

User ID to update

name
string

User's full name

email
string <email>

User's email address

institution
string

User's affiliated institution

role
string
Enum: "admin" "researcher" "student" "viewer"

User's role in the system

databases
Array of strings

List of databases the user should have access to

isActive
boolean

Whether the user account is active

field
required
string

Field name to update

required
string or number or boolean

New value for the field

Responses

Request samples

Content type
application/json
Example
{
  • "method": "setfield",
  • "field": "name",
  • "value": "Jane Doe"
}

Response samples

Content type
application/json
{
  • "message": "User updated successfully"
}

Check current user's role

Returns the current authenticated user's role information

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "isAdmin": true
}

Get user authentication and profile status

Retrieves the current user's authentication status and database profile information. Used to determine if a user needs to complete their profile setup after authentication.

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
Example
{
  • "user": {
    },
  • "dbuser": {
    },
  • "needsIdentification": false
}

Samples

Biological sample management and taxonomic data

Retrieve all samples

Get a list of all samples in the database. Supports query parameters for filtering and pagination.

Authorizations:
bearerAuthsessionAuth
query Parameters
method
string
Value: "get-schema"

Special method to get sample schema instead of data

type
string
Enum: "animal" "silk" "other"

Filter samples by type

family
string

Filter samples by taxonomic family

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update samples

Create new samples, update existing ones, or perform bulk operations

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
string
Enum: "update" "setfield" "incrementfield"

Operation type

id
string

Sample ID for update operations

field
string

Field name to update

value
any

New value for the field

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Nephila clavipes #15",
  • "type": "animal",
  • "family": "Araneidae",
  • "genus": "Nephila",
  • "species": "clavipes"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "insertedId": "string"
}

Traits

Trait measurements and statistical analysis

Retrieve trait measurements

Get a list of trait measurements with optional filtering by type and optional inclusion of sample features for enhanced data analysis.

Authorizations:
bearerAuthsessionAuth
query Parameters
includeSampleFeatures
boolean
Example: includeSampleFeatures=true

Include associated sample information in the response

type
string
Example: type=silk_diameter

Filter traits by specific type

id
string
Example: id=507f1f77bcf86cd799439011

Retrieve a specific trait by its ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create, update, or delete trait measurements

Handles multiple trait operations based on the method field:

  • create: Add a new trait measurement
  • update: Modify an existing trait measurement
  • delete: Remove a trait measurement
  • setfield: Update a specific field of a trait
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
required
string
Value: "create"

Action to perform

type
required
string

Type of trait measurement

sampleId
required
string

Reference to the sample

responsible
required
string

ID of the user responsible for this measurement

date
required
string <date>

Date when the measurement was taken

measurement
number

The measured value

unit
string

Unit of measurement

detail
string

Additional details about the measurement

equipment
string

Equipment used for measurement

nfibres
string

Number of fibers measured

listvals
Array of numbers

Individual measurement values

notes
string

Additional notes about the measurement

filesId
Array of strings

Associated file IDs

Responses

Request samples

Content type
application/json
{
  • "method": "create",
  • "type": "silk_diameter",
  • "sampleId": "507f1f77bcf86cd799439012",
  • "responsible": "507f1f77bcf86cd799439013",
  • "date": "2024-03-15",
  • "measurement": 2.5,
  • "unit": "μm",
  • "equipment": "SEM",
  • "nfibres": "1",
  • "detail": "major ampullate silk",
  • "notes": "Good quality sample"
}

Response samples

Content type
application/json
{
  • "message": "Trait created successfully",
  • "id": "507f1f77bcf86cd799439011"
}

Experiments

Experimental procedures and raw data management

Retrieve experiments

Get a list of experiments with optional inclusion of raw experimental data and filtering options.

Authorizations:
bearerAuthsessionAuth
query Parameters
includeRawData
boolean
Example: includeRawData=true

Include raw experimental data in the response

includeOriginalData
boolean

Include original (unprocessed) data instead of current data

type
string
Example: type=mechanical_test

Filter experiments by type

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create, update, or delete experiments

Handles multiple experiment operations based on the method field:

  • create: Add a new experiment
  • update: Modify an existing experiment
  • delete: Remove an experiment
  • addRawData: Add raw data to an experiment
  • processData: Process raw experimental data
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
required
string
Value: "create"

Action to perform

name
required
string

Experiment name

type
required
string

Type of experiment

description
string

Detailed description of the experiment

responsible
required
string

ID of the user responsible for this experiment

date
string <date>

Experiment date

samples
Array of strings

List of sample IDs used in this experiment

equipment
string

Equipment used for the experiment

conditions
object

Environmental or experimental conditions

Responses

Request samples

Content type
application/json
{
  • "method": "create",
  • "name": "Silk tensile strength study",
  • "type": "mechanical_test",
  • "description": "Testing the tensile strength of spider silk",
  • "responsible": "507f1f77bcf86cd799439013",
  • "date": "2024-03-15",
  • "samples": [
    ],
  • "equipment": "Instron 5544"
}

Response samples

Content type
application/json
{
  • "message": "Experiment created successfully",
  • "id": "507f1f77bcf86cd799439011"
}

Files

File upload, storage, and metadata management

Retrieve all files

Get a list of all files stored in the system with their metadata.

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload files

Upload one or more files to the system. Files are stored with metadata and can be linked to specific entries.

Authorizations:
bearerAuthsessionAuth
Request Body schema: multipart/form-data
files
Array of strings <binary>

Files to upload

entryType
string

Type of entry to link files to

deferredLink
boolean

Whether to defer linking until later

mediaType
string

Expected media type

Responses

Response samples

Content type
application/json
{
  • "message": "Files uploaded successfully",
  • "fileIds": [
    ]
}

Link a file to an entry

Links a file to a specific entry (sample, trait, or experiment). If the file was temporary, it will be moved to the appropriate directory structure and marked as permanent. The entry's logbook will be updated with the linking action.

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
fileId
required
string^[0-9a-fA-F]{24}$

MongoDB ObjectId of the file to link

entryType
required
string
Enum: "sample" "trait" "experiment"

Type of entry to link the file to

entryId
required
string^[0-9a-fA-F]{24}$

MongoDB ObjectId of the entry to link the file to

Responses

Request samples

Content type
application/json
Example
{
  • "fileId": "507f1f77bcf86cd799439011",
  • "entryType": "sample",
  • "entryId": "507f1f77bcf86cd799439012"
}

Response samples

Content type
application/json
{
  • "success": true
}

Download a file by ID

Downloads a file from the server using its database ID. The file metadata is retrieved from the database and the actual file is served from the file system.

Authorizations:
bearerAuthsessionAuth
query Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: id=507f1f77bcf86cd799439011

MongoDB ObjectId of the file to download

Responses

Response samples

Content type
application/json
{
  • "error": "File ID is required."
}

Utilities

Helper functions for geocoding, image search, and data processing

Search for species images in GBIF

Search the Global Biodiversity Information Facility (GBIF) database for images of species based on a query string.

Authorizations:
bearerAuthsessionAuth
query Parameters
query
required
string
Example: query=Araneus diadematus

Species name or search query

Responses

Response samples

Content type
application/json
{}

Reverse geocode coordinates to address

Converts latitude and longitude coordinates to a human-readable address using OpenStreetMap's Nominatim service

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
lat
required
number <float> [ -90 .. 90 ]

Latitude coordinate

lon
required
number <float> [ -180 .. 180 ]

Longitude coordinate

Responses

Request samples

Content type
application/json
{
  • "lat": 52.52,
  • "lon": 13.405
}

Response samples

Content type
application/json
{
  • "location": {
    }
}

Method not allowed

GET method is not supported for this endpoint

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Method not allowed"
}

Get system notifications

Retrieves all current system notifications from an external JSON source with intelligent caching and fallback mechanisms.

Caching Strategy:

  • Responses are cached for 2.5 minutes to improve performance
  • Fresh data is fetched from external source when cache expires
  • Cache is updated automatically on successful external fetch Fallback Strategy:
  1. External JSON source (currently hardcoded due to environment variable configuration issues)
  2. Cached data (even if expired) when external source fails
  3. Local notifications.json file as final fallback

Current Implementation Note:

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
Example

Fast response from in-memory cache

null

Generate labeled QR code image

Downloads a QR code image from a URL and adds text labels to the right side of the image

Authorizations:
bearerAuthsessionAuth
query Parameters
qrcodeurl
required
string <uri>
Example: qrcodeurl=https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=Sample

URL of the QR code image to modify

labelwidth
integer [ 100 .. 1000 ]
Default: 400
Example: labelwidth=400

Width of the label area in pixels

label1
string <= 50 characters
Example: label1=Sample ID: 001

First label text (truncated if longer than 12 characters)

label2
string <= 50 characters
Example: label2=Date: 2024-03-15

Second label text (truncated if longer than 12 characters)

label3
string <= 50 characters
Example: label3=Location: Lab A

Third label text (truncated if longer than 12 characters)

Responses

Response samples

Content type
application/json
{
  • "error": "Failed to process image"
}

Geocode location names to coordinates

Convert location names or addresses to latitude/longitude coordinates using OpenStreetMap Nominatim service.

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
location
required
string

Location name or address to geocode

Responses

Request samples

Content type
application/json
Example
{
  • "location": "Berlin, Germany"
}

Response samples

Content type
application/json
{
  • "coordinates": {
    }
}

Check API status

Simple health check endpoint for the taxonomic name checking service

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "message": "checkname API working"
}

Validate and correct taxonomic names

Validates and corrects scientific names using various taxonomic databases. Supports two methods:

  • correctName: Returns the corrected/standardized name
  • fullTaxaInfo: Returns complete taxonomic hierarchy information

Data sources:

  • WSC: World Spider Catalog (spider-specific)
  • GNames: Global Names Verifier (general taxa) - uses data sources 1, 12, 13 (Catalogue of Life, Encyclopedia of Life, GBIF)
  • auto: Tries WSC first, falls back to GNames
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
taxa
required
string

Scientific name to check or validate

method
string
Default: "correctName"
Enum: "correctName" "fullTaxaInfo"

Type of operation to perform

source
string
Default: "auto"
Enum: "auto" "WSC" "GNames"

Data source for name checking (WSC = World Spider Catalog, GNames = Global Names Verifier)

family
string

Optional family name to provide taxonomic context (used with GNames)

Responses

Request samples

Content type
application/json
Example
{
  • "taxa": "Araneus diadematus",
  • "method": "correctName",
  • "source": "auto"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": "Araneus diadematus",
  • "source": "WSC"
}

Settings

Get main settings

Retrieve the main settings configuration including ID generation and lab info

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update main settings

Update the main settings configuration

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
object
object

Responses

Request samples

Content type
application/json
{
  • "idGeneration": {
    },
  • "labInfo": {
    }
}

Sample

Retrieve a single sample

Get a single sample by name, ID, or other query parameters using JSON body

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
name
string

Filter by sample name (exact match)

id
string

Filter by sample ID

type
string
Enum: "animal" "silk" "subsample" "other"

Filter by sample type

Responses

Request samples

Content type
application/json
Example
{
  • "name": "MACN-Ar 47148",
  • "type": "animal"
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "name": "Araneus diadematus #42",
  • "type": "animal",
  • "family": "Araneidae",
  • "genus": "Araneus",
  • "species": "diadematus",
  • "location": "Berlin, Germany",
  • "date": "2024-03-15",
  • "collector": "Dr. Smith"
}

Documentation

Get dynamically generated OpenAPI specification

This endpoint uses swagger-jsdoc to automatically scan API route files and generate OpenAPI spec from JSDoc comments

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{ }

Databases

Get available databases

Retrieve list of available databases that can be assigned to users

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "databases": [
    ]
}

Add a new database

Add a new database to the available databases list (admin only)

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
database
string

Database name to add

Responses

Request samples

Content type
application/json
{
  • "database": "newproject"
}

Configuration

Retrieve configuration

Get all configuration types or a specific type

Authorizations:
bearerAuthsessionAuth
query Parameters
type
string
Enum: "sampletypes" "traittypes" "equipmenttypes" "samplesubtypes" "silkcategories" "siprefixes"

Specific configuration type to retrieve

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "type": "sampletypes",
  • "data": [
    ],
  • "version": 0,
  • "lastModified": "2019-08-24T14:15:22Z",
  • "modifiedBy": "string",
  • "isDefault": true
}

Create or update configuration

Handle configuration operations:

  • create: Create new configuration type
  • update: Update entire configuration type
  • additem: Add single item to configuration
  • updateitem: Update single item in configuration
  • deleteitem: Remove single item from configuration
  • seed: Initialize with default data
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
string
Enum: "create" "update" "additem" "updateitem" "deleteitem" "seed"
type
string
Enum: "sampletypes" "traittypes" "equipmenttypes" "samplesubtypes" "silkcategories" "siprefixes"
Array of objects (ConfigItem)
object (ConfigItem)
oldValue
string

For updateitem - the current value to update

Responses

Request samples

Content type
application/json
{
  • "method": "create",
  • "type": "sampletypes",
  • "data": [
    ],
  • "item": {
    },
  • "oldValue": "string"
}

Seed database with default configurations

Replace existing configurations with defaults or create them if they don't exist

Authorizations:
bearerAuthsessionAuth

Responses