API design

[iishiishii]

Goal

Create a general boilerplate for a full stack web app demo

Features

Server-side

• FastAPI
• Postgres
• Celery (to handle async tasks)

Client-side

• Typescript
• React
• Niivue

Description

From our discussion, there're two approaches:

1. Develop a JSON specification based on NVDocument with the encoded image. The request body would include JSON file.
2. JSON body about the Niivue scene with links to the static image files on disk that need to be loaded in the scene. These could be considered the hypermedia controls in an API route’s implementation. The request body would include scene.json and images.

Athough I like to avoid duplicated work so was thinking of reusing NVDocument but that seems to require a lot more changes from Niivue API so using pure JSON with hypermedia would be a better idea. Any thoughts on having download path and delete path in the hypermedia like this?

  "links": {
    "self": "/api/scenes/123",
    "download": "/api/scenes/123/download",
    "delete": "/api/scenes/123"
  }

Still a WIP specs, let me know if you find anything redundant.

API specs

GET /scene/{request_id}

Description: List all results from request with request_id

Path parameters
request_id: string The request unique identifier

Response

[
  {
    "request_id":	"string", // The analysis job's unique identifier. This is a UUIDv4 that was generated by the processing service when the analysis request was received. Example: a8adfe49-d88f-4656-bb8c-7c2272358ccd
    "status":	"string", // The status of the analysis job. Example: success. Enum: pending, success, failed
    "links": {
      "self": "/api/scenes/{request_id}",
      "download": "/api/scenes/{request_id}/download",
      "delete": "/api/scenes/{request_id}"
    }
    "created_at":	"string (date-time)", // The date and time the analysis request was received. Example: 2025-03-12T13:10:05Z
  }
]

GET /scene/{request_id}/download

Description: Download results from request with request_id

Path parameters
request_id: string The request unique identifier

Response

[
  {
    "request_id":	"string", // The analysis job's unique identifier. This is a UUIDv4 that was generated by the processing service when the analysis request was received. Example: a8adfe49-d88f-4656-bb8c-7c2272358ccd
    "status":	"string", // The status of the download. Example: success. Enum: started, failed
    "results":  {
      "schemaId": "string",    // e.g. "scene-id-freesurefer"
      "schemaUrl": "string",   // URL for the schema  /scene/{request_id}/files
      "version": "string",      // e.g. "0.0.1"
      "metadata": {
        "createdAt": "string"  // ISO 8601 date format, e.g., "2025-04-07T12:00:00Z"
      },
      "niivueParameters": {
        "meshList": [
          {
            "url": "string",       // URL of the mesh file
            "rgba255": [number, number, number, number] // Array of RGBA values (0-255)
          }
        ],
        "volumeList": [
              {
                "url": "https://niivue.github.io/niivue/images/mni152.nii.gz",
                "colormap": "gray",
                "visible": true,
                "opacity": 1
              }
        ]
      } 
    }
  }
]

DELETE /scene/{request_id}

Description: Delete results from request with request_id

Path parameters
request_id: string The request unique identifier

Response

[
  {
    "request_id":	"string", // The analysis job's unique identifier. This is a UUIDv4 that was generated by the processing service when the analysis request was received. Example: a8adfe49-d88f-4656-bb8c-7c2272358ccd
    "status":	"string", // The status of the download. Example: success. Enum: started, failed
  }
]

POST /scene

Description: Submits a request to process images.
Request Body:

{
  "metadata": {
    "createdAt": "string"  // ISO 8601 date format, e.g., "2025-04-07T12:00:00Z"
  },
  "niivueParameters": {
    "volumeList": [
          {
            "url": "https://niivue.github.io/niivue/images/mni152.nii.gz",
            "colormap": "gray",
            "visible": true,
            "opacity": 1
          }
     ]
  }
}

Query parameters
processing_task: string // Task from the given list to process image (eg. Figure below)

Responses

[
  {
    "request_id":	"string", // The analysis job's unique identifier. This is a UUIDv4 that was generated by the processing service when the analysis request was received. Example: a8adfe49-d88f-4656-bb8c-7c2272358ccd
    "status":	"string", // The status of the analysis job. Example: success. Enum: pending, success, failed
    "created_at":	"string (date-time)", // The date and time the analysis request was received. Example: 2025-03-12T13:10:05Z
  }
]

@pwighton what do you think of schemaId and schemaUrl to be in the format of "sceneId-processTool" and /scene/{request_id}/files as I did the the download endpoints above? Not sure if you have another idea for them.

@neurolabusc @pwighton @cdrake @hanayik

Tasks

• niimath first processing tool with args
• prepare dummy data
• backend and communication with dummy data
• scene specs from Niivue team (json specs vs nvd)
• backend cloud deployment with terraform
• document the implementation

[pwighton]

Thanks @iishiishii for starting this discussion.

I very much prefer approach 2) where the neuroimaging files are seperated from the scene defintion. I think this approach will make it the most useful to the neuroimaging community.

I'll admit this is outside of my area of expertise, so I'll defer to @neurolabusc @hanayik and @cdrake, but I think we might be conflating functionality.

The way I see it, we need functionality for 2 differfent tasks:

• A way to view/create/modify/delete scenes, including the neuroimaging files a scene references.
• A way to exceute backend processsing tasks.

I've spent more time thinking about the first task than the second, and I think the API endpoints we need for that would look something like:

• GET /file/
  • List all neuroimaging files
• GET /file/{filepath}
  • Returns information about the neuroimaging file (filename, size, hash, etc)
• GET /file/download/{filepath}
  • Downloads the neuroimaging file
• POST /file/{filepath}
  • Uploads a neuroimaging file
• DELETE /file/{filepath}
  • Deletes a neuroimaging file
• GET /scene/
  • List all scences
• GET /scene/{scene_id}
  • Returns a specific scene
• DELETE /scene/{scene_id}
  • Deletes a specific scene
  • The request body should indicate if the referenced neuroimaging files should be deleted as well
• POST /scene/
  • Uploads a scene and return a new scene_id
  • A call to POST /scene/ should also make calls POST /file/{filepath} to upload the neuroimaging files associated with the scene, if neccesary.

For the second task, executing processes on the backend, I'm not sure a scene is the best interface for this, however if there is a natual mapping between the current scene a user is interacting with and the processing task, perhaps the job could be submitted automatically for the user.

The endpoints for that might look something like:

• GET /proc/
  • Lists all processes and their status
• GET /proc/{proc_id}
  • Retuns detailed infomation about a process
• POST /proc
  • Submits a job for processing
    Request body:

{
  "metadata": {
    "createdAt": "string"  // ISO 8601 date format, e.g., "2025-04-07T12:00:00Z"
  },
  "Task" : "string" // e.g. FreeSurfer, registrtion, etc
  "InputFiles": [
    "file1.nii.gz",
    "file2.nii.gz"  
  ],
  "Parameters": {
    "output_file": "file3.nii.gz",
    "cost_function": "mutual_information" 
  }
}