Skip to content

REST API EndpointsLink

This document describes the REST API endpoints for the PlantDB (Plant Database) system, which provides access to plant scan datasets, images, point clouds, meshes, and related data through RESTful endpoints.

OverviewLink

The PlantDB REST API is implemented using Flask and Flask-RESTful, providing a comprehensive interface for managing and accessing plant-related datasets. The Python implementation is located in the plantdb.server.rest_api module, and the CLI server is started using the fsdb_rest_api CLI.

Base URL: http://127.0.0.1:5000 (default, configurable) API URL prefix: /api/v1 (default, configurable)

Table of ContentsLink

  1. Getting Started
  2. Health and Status
  3. Database Management
  4. Authentication
  5. Scans
  6. Assets

Getting StartedLink

Starting the ServerLink

To run the server with a temporary test database: 

fsdb_rest_api --test

For more explanations, have a look at how to run the REST API.

AuthenticationLink

Some endpoints require authentication. Use the /auth/register, /auth/login endpoints to obtain authentication tokens.

Health and StatusLink

GET /healthLink

REST API status

  • Description: Check API server health and database connectivity
  • Response: JSON with health status information
  • Example: GET /health

Database ManagementLink

GET /refresh/Link

Reload the whole database

  • Description: Refresh the list of scans in the database
  • Response: HTTP 200 on completion
  • Example: GET /refresh/

GET /refresh/{scan_id}Link

Reload the scan

  • Description: Refresh a specific scan in the database
  • Path Parameters:
    • scan_id: Unique identifier of the scan
  • Response: HTTP 200 on completion
  • Example: GET /refresh/real_plant_analyzed

AuthenticationLink

POST /auth/loginLink

User login

  • Description: Authenticate user and return authentication token
  • Request Body: JSON with username and password
  • Response: Authentication token

POST /auth/logoutLink

User logout

  • Description: Invalidate user authentication token
  • Response: Success message

POST /auth/registerLink

New user registration

  • Description: Register a new user account
  • Request Body: JSON with user details
  • Response: User registration confirmation

GET /auth/tokens/refreshLink

Retrieve a specific scan

  • Description: Refresh authentication token
  • Response: New authentication token

GET /auth/tokens/validationLink

Retrieve a specific scan

  • Description: Validate authentication token
  • Response: Token validation status

POST /auth/tokens/create-api-tokenLink

Create API token

  • Description: Create a new API token for programmatic access
  • Request Body: JSON with token details
  • Response: Created API token

ScansLink

GET /scans/Link

List scans

  • Description: Retrieve a list of all available scan datasets
  • Query Parameters:
    • filterQuery (optional): Filter scans based on metadata content
  • Response: JSON array of scan summaries

GET /scans/infoLink

List scans

  • Description: Get comprehensive scan information in tabular format
  • Query Parameters:
    • filterQuery (optional): Filter scans
  • Response: JSON object with detailed scan metadata, file counts, and task status

GET /scans/{scan_id}/Link

Retrieve a specific scan

  • Description: Get detailed information about a specific scan dataset
  • Path Parameters:
    • scan_id: Unique identifier of the scan
  • Response: JSON object with comprehensive scan details including camera parameters, poses, and file URIs

POST /scans/{scan_id}/Link

Create a new scan

  • Description: Create a new scan dataset
  • Path Parameters:
    • scan_id: Unique identifier of the scan
  • Request Body: JSON with scan metadata
  • Response: Scan creation confirmation

GET /scans/{scan_id}/metadata/Link

Get scan metadata

  • Description: Retrieve metadata for a specific scan
  • Path Parameters:
    • scan_id: Unique identifier of the scan
  • Response: JSON with scan metadata

POST /scans/{scan_id}/metadata/Link

Update scan metadata

  • Description: Update metadata for a specific scan
  • Path Parameters:
    • scan_id: Unique identifier of the scan
  • Request Body: JSON with updated metadata
  • Response: Metadata update confirmation

GET /scans/{scan_id}/filesetsLink

List filesets for scan

  • Description: List all filesets within a scan
  • Path Parameters:
    • scan_id: Unique identifier of the scan
  • Response: JSON array of fileset identifiers

FilesetsLink

POST /filesets/{scan_id}/{fileset_id}/Link

Create a new fileset

  • Description: Create a new fileset within a scan
  • Path Parameters:
    • scan_id: Unique identifier of the scan
    • fileset_id: Unique identifier of the fileset
  • Request Body: JSON with fileset information
  • Response: Fileset creation confirmation

GET /filesets/{scan_id}/{fileset_id}/metadata/Link

Get fileset metadata

  • Description: Retrieve metadata for a specific fileset
  • Path Parameters:
    • scan_id: Unique identifier of the scan
    • fileset_id: Unique identifier of the fileset
  • Response: JSON with fileset metadata

POST /filesets/{scan_id}/{fileset_id}/metadata/Link

Update fileset metadata

  • Description: Update metadata for a specific fileset
  • Path Parameters:
    • scan_id: Unique identifier of the scan
    • fileset_id: Unique identifier of the fileset
  • Request Body: JSON with updated metadata
  • Response: Metadata update confirmation

GET /filesets/{scan_id}/{fileset_id}/filesLink

List files

  • Description: List all files within a fileset
  • Path Parameters:
    • scan_id: Unique identifier of the scan
    • fileset_id: Unique identifier of the fileset
  • Response: JSON array of file identifiers

FilesLink

GET /files/{scan_id}/{fileset_id}/{file_id}Link

Retrieve file

  • Description: Get details about a specific file
  • Path Parameters:
    • scan_id: Unique identifier of the scan
    • fileset_id: Unique identifier of the fileset
    • file_id: Unique identifier of the file
  • Response: JSON with file details

POST /files/{scan_id}/{fileset_id}/{file_id}Link

Create a new file

  • Description: Add a new file to a fileset
  • Path Parameters:
    • scan_id: Unique identifier of the scan
    • fileset_id: Unique identifier of the fileset
    • file_id: Unique identifier of the file
  • Request Body: File data and metadata
  • Response: File creation confirmation

GET /files/{scan_id}/{fileset_id}/{file_id}/metadata/Link

Get file metadata

  • Description: Retrieve metadata for a specific file
  • Path Parameters:
    • scan_id: Unique identifier of the scan
    • fileset_id: Unique identifier of the fileset
    • file_id: Unique identifier of the file
  • Response: JSON with file metadata

POST /files/{scan_id}/{fileset_id}/{file_id}/metadata/Link

Update file metadata

  • Description: Update metadata for a specific file
  • Path Parameters:
    • scan_id: Unique identifier of the scan
    • fileset_id: Unique identifier of the fileset
    • file_id: Unique identifier of the file
  • Request Body: JSON with updated metadata
  • Response: Metadata update confirmation

AssetsLink

GET /assets/files/{file_path}Link

Retrieve a specific scan

  • Description: Retrieve any file from the database using its path
  • Path Parameters:
    • file_path: Full path to the file within the database
  • Response: File content (binary or text)

GET /assets/archive/{scan_id}Link

Retrieve scan archive

  • Description: Download a complete dataset as a ZIP file
  • Path Parameters:
    • scan_id: Scan identifier to archive
  • Response: ZIP file containing the entire dataset

POST /assets/archive/{scan_id}Link

Create a new scan by uploading a scan archive

  • Description: Upload a ZIP file to create a new scan dataset
  • Path Parameters:
    • scan_id: Target scan identifier
  • Form Data:
    • file_upload: The ZIP file to upload
  • Response: Scan creation confirmation

GET /assets/image/{scan_id}/{fileset_id}/{file_id}Link

Get image

  • Description: Retrieve an image file
  • Path Parameters:
    • scan_id: Scan identifier
    • fileset_id: Fileset identifier (usually 'images')
    • file_id: Image file identifier (without extension)
  • Response: Image file (JPEG/PNG)

POST /assets/image/{scan_id}/{fileset_id}/{file_id}Link

Create a new image

  • Description: Upload an image file to a specific scan dataset
  • Path Parameters:
    • scan_id: Scan identifier
    • fileset_id: Fileset identifier (usually 'images')
    • file_id: Image file identifier (without extension)
  • Form Data:
    • file_upload: The image file to upload
  • Response: Image creation confirmation

GET /assets/pointcloud/{scan_id}Link

Retrieve scan pointcloud

  • Description: Retrieve point cloud files for a scan
  • Path Parameters:
    • scan_id: Scan identifier
  • Response: Point cloud file (PLY format)

GET /assets/mesh/{scan_id}Link

Retrieve scan triangular mesh

  • Description: Retrieve 3D mesh files for a scan
  • Path Parameters:
    • scan_id: Scan identifier
  • Response: Mesh file (PLY format)

GET /assets/sequence/{scan_id}Link

Retrieve scan sequence

  • Description: Retrieve sequence-related information for a scan
  • Path Parameters:
    • scan_id: Scan identifier
  • Response: JSON with sequence data

GET /assets/skeleton/{scan_id}Link

Retrieve scan skeleton

  • Description: Retrieve curve skeleton information for a scan
  • Path Parameters:
    • scan_id: Scan identifier
  • Response: JSON with curve skeleton data