Developer FAQ


For an overview of BaseSpace and App Development, please refer to the Getting Started.

What is BaseSpace?

BaseSpace is a cloud-based service that was created to store sequencing data and to allow analysis or visualization bioinformatics software to read this data from the cloud.

Do developers have to pay for access to the API or the SDKs or Native Apps?

No, with the public launch of the development portal, anyone is able to create apps to run on BaseSpace data.

Do I start with the API or the SDKs or Native Apps?

In most cases, a developer will start with the SDKs before digging into the API. While there is extensive API documentation, the SDKs will be much easier to understand and execute for a new app developer. Using the SDKs will provide the developer with code that is much easier to understand in a language that may be more familiar than the API.

If a developer is oriented towards command-line applications, then the Native application is a great place to begin. Native apps make it easy to take a command-line tool and create a BaseSpace app from it.

What if I just want to analyze my own sequencing data?

This is supported in BaseSpace. Users of BaseSpace have the option of uploading their own data and keeping it private. Any applications that are created by the user in My Apps are shown in that user's BaseSpace UI, they do not have to be published to be seen in this way.

How does the BaseSpace App Store work?

Each app that is created and published will appear in the BaseSpace App Store. The user will be able to reach the App Store from the BaseSpace UI. The App Store can be searched and groups apps by category and type. Each app's page in the App Store will have the app's name, developer name and contact information, more detailed information about the app, screenshots, a logo/icon, and a few other parameters to give the user ample information about an app before purchasing it.

What costs will the developer have?

There are no development costs. However, Illumina, Inc. retains 30% of revenue generated by an app plus any data transfer cost.

For Web applications, the developer pays the cost of hosting their application but there is no cost to create an application in BaseSpace that connects to it.

For Native applications, developers that charge for their applications are required to also charge the customer the estimated compute cost for the application which goes directly to Illumina.

Can a developer test their apps on BaseSpace data?

Yes, a developer can test their app through My Apps and test it on BaseSpace data that they have access to. Also, the logged in user on BaseSpace can use any apps that they have in development on their own data in BaseSpace. This means that a developer may create an app in My Apps, then go to the BaseSpace UI where they would be able to see and launch this app.

What types of files are typically associated with which resources?

Runs: Sequencing instrument upload files

  • Runs -> Files -> .bcl files

Samples: Demultiplexed Runs .bcl files

  • Projects -> Samples -> Files -> .fastq files

AppResults: alignment and variant calling on Samples FASTq files

  • Projects -> AppResults -> Files -> .vcf, .bam, or other files

These are the file types typically associated with these resources, however there can be variation in file types in each resource.

Will users need to set up their configuration before the app runs and, if so, what will the app need from them?

Yes, the Formbuilder tool can be used to create an input form for the application using JSON. This input form is a template that will be displayed any time the app is launched and allows the user to select any items the developer has configured before the app analysis is executed. For more information, please refer to the Form Builder Documentation.

Can the outputs of the app drive a web-based UI?

Yes, you can use the Report Builder tool to create static web templates to visualize the output from your application. For more information, please refer to the Report Builder Documentation.

Web/Desktop Apps

Where do I find my client id and client secret?

client_id and client_secret are found in My Apps after creating an app. They are automatically given for each application that is created in My Apps and unique to that application.

What is an access token and what do I have to do to get one?

An access token is a value that is passed from the application to the API which tells the API that the application has a certain amount of access to a certain user's data.

  1. When a user launches an app, the app will ask the user for a specific level of access (described in BaseSpace Permissions.)

  2. The user sees the OAuth dialog, which shows them the level of access that the app is requesting, which resources it will access/modify, and allow the user to grant or deny permission to the app.

  3. If the user grants permission, the app is given a authorization code which the app passes to the API, along with its client id and client secret, to exchange it for an access token.

These steps are described in more detail in App Triggering from BaseSpace and Obtaining Access Tokens.

Native Apps

What is the difference between the Send to Local Agent and Continue buttons on the input form?

Send to Local Agent - Send the job for the analysis to the development machine where the developer has set up their VM or the developer has configured the machine with SpaceDock, Docker, and BSFS. The job is run outside of BaseSpace but the data comes from and goes back to BaseSpace.

Continue - Send the job for the analysis to BaseSpace's cloud infrastructure. The job will be executed in BaseSpace's infrastructure and not on the developer's local machine. This is the same mechanism that users use to run applications in BaseSpace.

What inputs and outputs will your app require?

Make sure that your starting point (input) is either FASTQ, BAM, or VCF files because these are the most common file types in BaseSpace. Starting from BCL files is not an option. Some apps may not require an input file type and are simply using API metadata, in which case the input would be the metadata in the API.

Does your app require access to external sources?

At the moment, Native apps can communicate with external resources. This means that your dependency data can be hosted externally and be accessed from within your docker image for the native app.

Are any reference genomes available? If so, how do I gain access and is there a list of what is available?

Yes, there is a set of reference genome data that is available but it can only be accessed once the app is given the ability to launch in the BaseSpace infrastructure using the Continue button in the input form. The genomes will automatically be mounted to your docker container at the /genomes location. For more information, please refer to the Native App Conventions Documentaton.