iGEM upload API

An API that interfaces with the iGEM upload tool to allow automatic file management and organisation.
The goal is to entirely replace the manual process of uploading files to the iGEM server, which is time-consuming and very user-unfriendly.

Caution

The iGEM internal API is not officially supposed to be used by the public. This entire project is reverse-engineered from the upload tool web app and may break at any time. Please use at your own discretion.

Disclaimer

Important

⚠️ This project is not affiliated with or endorsed by the iGEM Foundation.

Installation

Node

npm install igem-upload-api

Usage

// Import the main API export; see below for importing types
import igemUploadApi from 'igem-upload-api';

// Wrap in an async function to use await
(async () => {

    // Create an instance of the iGEM API
    const TEAM_NUMBER = 1234;
    const USERNAME = 'lowercase-username-you-use-to-login';
    const PASSWORD = 'password-you-use-to-login';
    const api = new igemUploadApi(TEAM_NUMBER, USERNAME, PASSWORD);

    // Start a new session
    await api.startSession();

    // List the contents a remote directory non-recursively
    await api.listDirectory([]);                // Remote root directory
    await api.listDirectory(['']);              // Remote root directory
    await api.listDirectory(['foo']);           // Remote 'foo' directory
    await api.listDirectory(['foo', 'bar']);    // Remote 'foo/bar' directory
    await api.listDirectory('foo/bar');         // Remote 'foo/bar' directory
    // Do something with the response
    const { folders: folders1, files: files1 } = await api.listDirectory([]);

    // Upload a file
    // Upload local 'path/to/file/image.png' to remote 'image.png'
    await api.uploadFile([], ['path', 'to', 'file'], 'image.png');
    await api.uploadFile([], 'path/to/file', 'image.png');
    // Upload local 'path/to/file/font.woff2' to remote 'foo/bar/font.woff2'
    await api.uploadFile(['foo', 'bar'], ['path', 'to', 'file'], 'font.woff2');
    await api.uploadFile('foo/bar', 'path/to/file', 'font.woff2');
    // Do something with the response
    const url = await api.uploadFile([], ['path', 'to', 'file'], 'image.png');

    // Delete a file
    // Delete 'image.png' from remote root directory
    await api.deleteFile([], 'image.png');
    // Delete 'icon.svg' from remote 'foo/bar' directory
    await api.deleteFile(['foo', 'bar'], 'icon.svg');

    // Upload a directory
    // Upload local 'path/to/assets' to remote 'assets'
    await api.uploadDirectory(['assets'], ['path', 'to', 'assets']);
    await api.uploadDirectory('assets', 'path/to/assets');
    // Do something with the response
    const remoteResourceUrls = await api.uploadDirectory(['assets'], ['path', 'to', 'assets']);

    // Purge a directory
    // Purge remote 'assets' directory non-recursively
    await api.purgeDirectory(['assets']);
    // Purge remote 'foo/bar' directory and its sub-directories recursively
    await api.purgeDirectory('foo/bar', true);

    // End the session
    await api.endSession();
})();

Caution

iGEM handles passwords in unencrypted plaintext. They are sent across the internet in plaintext form.
Please absolutely do not reuse your iGEM password for any other service.

Types

You can import types from the package to use in your own code.

// Import the main API export and some extra types
import igemUploadApi, { DirectoryListing, RemoteResourceData } from 'igem-upload-api';

// Here are all the importable types
import igemUploadApi, { DirectoryListing, RemoteResourceData, PathArrayableType, FileData, FolderData, FILE_TYPES } from 'igem-upload-api';

Of course, you can dig deeper and import internal types not listed here, but doing so is not recommended.

Note

Directory paths accept the following type:

type PathArrayableType = (string | number)[] | string;

Paths are automatically sanitised and coerced into valid paths. These directory patterns are supported but not recommended.

await api.listDirectory(['   foo', '  bar ']);  // Leading and/or trailing whitespace
await api.listDirectory(['foo', '', 'bar']);    // Empty string in array
await api.listDirectory('///');                 // Malformed path
await api.listDirectory('foo/../');             // Backtracking (local paths only)

API

new igemUploadApi(teamNumber: number, username: string, password: string): igemUploadApi

Creates a new instance of the iGEM upload tool API.

Argument	Required?	Type	Description
teamNumber	Yes	number	The team number of the iGEM team
username	Yes	string	The username used to log in to the iGEM website
password	Yes	string	The password used to log in to the iGEM website

Tip

If you are unsure about what the parameters are:

1. Go to the upload tool.
2. Log in with your iGEM credentials, these are the same as username and password.
3. Click on the team you want to upload files to. There should be only one team.
4. The URL should look like https://tools.igem.org/uploads/teams/1234, where 1234 is the teamNumber.

Caution

iGEM handles passwords in unencrypted plaintext. They are sent across the internet in plaintext form.
Please absolutely do not reuse your iGEM password for any other service.

igemUploadApi.startSession(): Promise<void>

Starts a new session with the iGEM upload tool API.

igemUploadApi.listDirectory(remoteDirectoryPath: PathArrayableType): Promise<DirectoryListing>

Lists the contents of a remote directory specified by the remoteDirectoryPath parameter non-recursively.

Returns an object with two optional arrays.

Key	Required?	Type	Description
folders	No	FolderData[]?	List of subdirectories
|___.Prefix	Yes	string	The URL path of the folder?
|___.Key	Yes	string	The path of the folder
|___.Name	Yes	string	The name of the folder
|___.Type	Yes	"Folder"
files	No	FileData[]?	List of files
|____.Key	Yes	string	The path of the file
|____.LastModified	Yes	string	The last modified date (ISO date time string )
|____.ETag	Yes	string	The ETag of the file
|____.Size	Yes	number	The size of the file (bytes)
|____.StorageClass	Yes	string	?
|____.Location	Yes	string	The URL of the file
|____.Name	Yes	string	The name of the file
|____.Type	Yes	string	The file extension

Example return object:

{
    "folders": [
        {
            "Prefix": "teams/1234/images/",
            "Key": "teams/1234/images/",
            "Name": "images",
            "Type": "Folder"
        }
    ],
    "files": [
        {
            "Key": "teams/1234/icon.svg",
            "LastModified": "2024-01-01T00:00:00.000Z",
            "ETag": "\"0123456789abcdef0123456789abcdef\"",
            "Size": 100,
            "StorageClass": "STANDARD",
            "Location": "https://static.igem.wiki/teams/1234/icon.svg",
            "Name": "icon.svg",
            "Type": "svg"
        }
    ]
}

igemUploadApi.uploadFile(remoteDirectoryPath: PathArrayableType, localDirectoryPath: PathArrayableType, fileName: string): Promise<string>

Uploads a file from the local system to the remote directory specified by remoteDirectoryPath. The file is located at localDirectoryPath and has the name fileName.

Returns the URL of the uploaded file.

igemUploadApi.deleteFile(remoteDirectoryPath: PathArrayableType, fileName: string): Promise<void>

Deletes a file from the remote directory specified by remoteDirectoryPath. The file to be deleted has the name fileName.

Warning

You should make sure the path is correct since the iGEM API does not provide any response to confirm the deletion.

igemUploadApi.uploadDirectory(remoteDirectoryPath: PathArrayableType, localDirectoryPath: PathArrayableType): Promise<RemoteResourceData[]>

Uploads a directory from the local system to the remote directory specified by remoteDirectoryPath. The directory is located at localDirectoryPath.

Returns an array of remote resources data.

Key	Required?	Type	Description
...	Yes	RemoteResourceData[]
|____.localFilePath	Yes	string	The local path of the file
|____.isSuccessful	Yes	boolean	Whether the upload was successful
|____.url	Conditional	string	The URL of the uploaded file; this property does not exist if isSuccessful is false

Example return object:

[
    {
        "localFilePath": "assets/icon.svg",
        "isSuccessful": true,
        "url": "https://static.igem.wiki/teams/1234/assets/icon.svg"
    },
    {
        "localFilePath": "assets/data.json",
        "isSuccessful": false
    }
]

Note that the url property will be null if the upload was unsuccessful. In the example case, data.json was rejected due to an invalid file extension.

igemUploadApi.purgeDirectory(remoteDirectoryPath: PathArrayableType, recursive: boolean = false): Promise<void>

Purges a directory from the remote directory specified by remotePath. If recursive is set to true, the subdirectories and their contents will also be deleted.

igemUploadApi.endSession(): Promise<void>

Ends the current session with the iGEM upload tool API.