API reference

This page summarizes the API provided by the Wave container service.

POST /container-token

This endpoint allows you to submit a request to access a private container repository via Wave, or build a container image on-the-fly with a Dockerfile or Conda recipe file.

The endpoint returns the name of the container request made available by Wave.

Request body

{
    containerImage: string,
    containerFile: string,
    containerConfig: {
        entrypoint: string[],
        cmd: string[],
        env: string[],
        workingDir: string
        layers: [
            {
                location: string,
                gzipDigest: string,
                gzipSize: string,
                tarDigest: string
            },
            ...
        ]
    },
    condaFile: string,
    spackFile: string,
    containerPlatform: string,
    buildRepository: string,
    cacheRepository: string,
    timestamp: string,
    fingerprint: string,
    freeze: boolean,
    towerAccessToken: string,
    towerRefreshToken: string,
    towerEndpoint: string,
    towerWorkspaceId: number,
}

container token request attributes

Attribute	Description
containerImage	Name of the container to be served, e.g., docker.io/library/ubuntu:latest (optional). If omitted, the containerFile must be provided.
containerConfig.entrypoint	The container entrypoint command e.g. ['/bin/bash']
containerConfig.cmd	The launch command to be used by the Wave container, e.g., ['echo', 'Hello world'] (optional).
containerConfig.env	The environment variables to be defined in the Wave container e.g. ['FOO=one','BAR=two'] (optional).
containerConfig.workingDir	The work directory to be used in the Wave container e.g. /some/work/dir (optional).
containerConfig.layers.location	Either a HTTP URL from where a container layer tar gzip file should be downloaded or tar gzip file base64 encoded and prefixed with data: string (optional).
containerConfig.layers.tarDigest	The SHA256checksum of the provided tar file e.g. sha256:a7c724b02....
containerConfig.layers.gzipDigest	The SHA256 checksum of the provided layer tar gzip file e.g. sha256:a7c724b02....
containerConfig.layers.gzipSize	The size in bytes of the the provided layer tar gzip file.
containerFile	Dockerfile used for building a new container encoded in base64 (optional). When provided, the attribute containerImage should be omitted.
condaFile	Conda environment file encoded as base64 string.
spackFile	Spack recipe file encoded as base64 string.
containerPlatform	Target container architecture of the built container e.g. linux/amd64 (optional). Currently only supporting amd64 and arm64.
buildRepository	Container repository where container builds should be pushed e.g. docker.io/user/my-image (optional).
cacheRepository	Container repository used to cache build layers docker.io/user/my-cache (optional).
timestamp	Request submission timestap using ISO-8601.
fingerprint	Request unique fingerprint.
freeze	The container provisioned will be stored in the specified repository in a permanently.
towerEndpoint	Seqera Platform service endpoint from where container repositories credentials are retrieved (optional). Default https://api.cloud.seqera.io.
towerAccessToken	Access token of the user account granting the access to the Seqera Platform service specified via towerEndpoint (optional).
towerWorkspaceId	ID of the Seqera Platform workspace from where the container repositories credentials are retrieved (optional). When omitted the personal workspace is used.

Response

{
    containerToken: string,
    targetImage: string,
    expiration: string
}

Attribute	Description
containerToken	The unique token identifying the Wave container request e.g. 0123456789.
targetImage	The Wave container image name e.g. wave.seqera.io/wt/0123456789/library/ubuntu:latest.
expiration	The expiration timestamp of the Wave container using ISO-8601 format.

POST /v1alpha2/container

This endpoint allows you to submit a request to access a private container repository via Wave, or build a container image on-the-fly with a Dockerfile or Conda recipe file.

The endpoint returns the name of the container request made available by Wave.

Request body

{
    containerImage: string,
    containerFile: string,
    containerConfig: {
        entrypoint: string[],
        cmd: string[],
        env: string[],
        workingDir: string
        layers: [
            {
                location: string,
                gzipDigest: string,
                gzipSize: string,
                tarDigest: string
            },
            ...
        ]
    },
    condaFile: string,
    spackFile: string,
    containerPlatform: string,
    buildRepository: string,
    cacheRepository: string,
    timestamp: string,
    fingerprint: string,
    freeze: boolean,
    towerAccessToken: string,
    towerRefreshToken: string,
    towerEndpoint: string,
    towerWorkspaceId: number,
    packages: {
                  type: string,
                  environment: string,
                  entries: string[],
                  channels: string[],
                  condaOpts: {
                                mambaImage: string,
                                commands: string[],
                                basePackages: string
                              }
                  spackOpts:{
                                commands: string[],
                                basePackages: string
                            }                     
                  
              }
}

Note: You can read the description of al attributes except packages from here

Attribute	Description
packages	This object specifies conda or spack packages environment information.
environment	The package environment file encoded as a base64 string.
type	This represents the type of package builder. you can use SPACK or CONDA.
entries	List of the packages names.
channels	List of conda channels, which will be used to download packages.
mambaImage	Name of the docker image to be used in building conda containers.
commands	Command to be included in the container.
basePackages	Names of base packages.

Response

{
    containerToken: string,
    targetImage: string,
    expiration: string,
    buildId: string,
    cached: boolean 
}

Examples

1. Create docker image with conda packages

Request

curl --location 'http://localhost:9090/v1alpha2/container' \
--header 'Content-Type: application/json' \
--data '{
    "packages":{
        "type": "CONDA",
        "entries": ["salmon", "bwa"],
        "channels": ["conda-forge", "bioconda"]
    }
}'

Response

{
    "containerToken":"732b73aa17c8",
    "targetImage":"0625dce899da.ngrok.app/wt/732b73aa17c8/hrma017/dev:salmon_bwa--5e49881e6ad74121",
    "expiration":"2024-04-09T21:19:01.715321Z",
    "buildId":"5e49881e6ad74121_1",
    "cached":false,
    "freeze":false
}

2. Create singularity image with conda packages

Request

curl --location 'http://localhost:9090/v1alpha2/container' \
--header 'Content-Type: application/json' \
--data '{
    "format": "sif",
    "containerPlatform": "arm64",
    "packages":{
        "type": "CONDA",
        "entries": ["salmon"],
        "channels": ["conda-forge", "bioconda"]
    },
    "freeze": true,
    "buildRepository": <CONTAINER_REPOSITORY>,
    "towerAccessToken":<YOUR_SEQERA_PLATFORM_TOWER_TOKEN>,
    "towerEndpoint": "http://localhost:8008/api"
}'

Response

{
    "targetImage":"oras://<CONTAINER_REPOSITORY>:salmon--6c084f2e43f86a78",
    "buildId":"6c084f2e43f86a78_1",
    "cached":false,
    "freeze":true
}

Note: You need to add your container registry credentials in seqera platform to use freeze feature which is a requirement for singularity.

/v1alpha1/builds/{buildId}/status

Provides status of build against buildId passed as path variable

Response

{
    serviceInfo: {
        id: string,
        status: string,
        startTime: string,
        duration: string,
        succeeded: boolean
    }
}

Note: status can only be PENDING or COMPLETED.

Example

% curl --location 'http://localhost:9090/v1alpha1/builds/6c084f2e43f86a78_1/status'
{
    "id":"6c084f2e43f86a78_1",
    "status":"COMPLETED",
    "startTime":"2024-04-09T20:31:35.355423Z",
    "duration":123.914989000,
    "succeeded":true
}

/service-info

Provides basic information about the service status.

Response

{
    serviceInfo: {
        version: string,
        commitId: string
    }
}

Metrics APIs based on Redis

These APIs provide usage (builds and pulls) metrics of Wave for a specific date and/or a specific organisation. These APIs required basic authentication, so you need to provide username and password while calling these APIs.

All Metrics API endpoints have these two query parameters, at least one needs to provided to fetch the metrics:

Name	Description	sample Value
date	Format: yyyy-mm-dd, The data of the required metrics.	2024-04-08
org	domain of the organisation used in their emails. e.g. org=seqera.io	seqera.io

Build Metrics API

These APIs are used to get the metrics about the container builds by Wave.

GET /v1alpha2/metrics/builds

This endpoint is used to get the total numbers of builds performed by Wave.

Response

{
    count: integer
}

Examples

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/builds?date=2024-04-08&org=seqera.io"
{"count":4}

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/builds?date=2024-04-08"
{"count":6}

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/builds?org=seqera.io"
{"count":4}

Pull Metrics API

These APIs are used to get the metrics about the container pulls through Wave.

GET /v1alpha2/metrics/pulls

This endpoint is used to get the total numbers of pulls performed through Wave.

Response

{
    count: integer
}

Examples

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/pulls?date=2024-04-08&org=seqera.io"
{"count":5}

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/pulls?date=2024-04-08"
{"count":7}

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/pulls?org=seqera.io"
{"count":5}

Fusion Pull Metrics API

These APIs are used to get the metrics about the fusion based container pulls through Wave.

GET /v1alpha2/metrics/fusion/pulls

This endpoint is used to get the total numbers of pulls of fusion based containers performed through Wave.

Response

{
    count: integer
}

Examples

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/fusion/pulls?date=2024-04-08&org=seqera.io"
{"count":2}

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/fusion/pulls?date=2024-04-08"
{"count":2}%

% curl -u foo:bar "http://localhost:9090/v1alpha2/metrics/fusion/pulls?org=seqera.io"
{"count":2}