Getting Started
What is BaseSpace?
BaseSpace is a powerful website where biologists and informaticians can easily store, analyze, and share genetic data.
Sequencing data from Illumina instruments, including MiSeq and HiSeq, are streamed in real-time over the Internet to BaseSpace. The data is automatically converted to standard file formats for analysis by Applications (Apps). Users launch Apps in BaseSpace with just a few mouse clicks to analyze and visualize their data.
Developers can create Apps using either the BaseSpace Application Programming Interface (API) or the Software Development Kits (SDKs) available for several programming languages. Both approaches offer safe and easy access to BaseSpace data for Apps to analyse, visualize, monitor, etc.
BaseSpace hopes to revolutionize the genetic field by creating an environment with large stores of sequencing data, which can be easily accessed and analyzed online with a store of applications.
Why Develop Apps for BaseSpace?
Sequencing data has traditionally been stored in non-centralized locations, which offer little uniformity of data management across locations. BaseSpace greatly simplifies access to sequencing data via data centralization and ease-of-use. BaseSpace offers the following benefits as a development platform:
- Easy access to data -- sequencing data is automatically uploaded from instrument to BaseSpace
- Consistent data retrieval -- with a few lines of code, access data with the BaseSpace API and SDKs
- Write once, execute many -- when non-Illumina apps are published within an enterprise domain or shared to specific users, users with access can see those apps in the app store
- Highly scalable -- data storage and analysis scales since BaseSpace is built on Amazon Web Services (AWS)
- Flexible app hosting -- apps can be hosted on any website, desktop or mobile application, or inside BaseSpace as a Native App
- Easy sharing -- users can easily share their data and results
For more information about BaseSpace, see the BaseSpace data sheet.
How is Data Stored and Analyzed in BaseSpace?
BaseSpace data is stored according to a data model that includes Runs, Samples, Projects, App Results, and App Sessions.
Following sequencing on an instrument, sequencing data is uploaded to BaseSpace as a Run. Run files (BCL files) are converted and demultiplexed, if necessary, in BaseSpace to create Samples (FASTQ files).
Samples are analyzed by launching Apps. Files that are output from Apps are stored in AppResults. For example, a resequencing app executes alignment and variant calling, and an AppResult is then created for each Sample. An AppResult generally contains BAM and VCF files, however it may also contain other file types. AppResults can be used as inputs to Apps as well. App Sessions are created to record every time an App is launched. Finally, Projects are simple containers that store Samples and AppResults.
How do Apps Access BaseSpace Data
Applications access data using the BaseSpace RESTful API. The API may be accessed via simple HTTPS requests using any programming language and is organized to allow you to get to the data you need quickly.
The SDKs are available for several programming languages and make it even easier for developers to write applications or to integrate existing ones. The SDKs work by exposing what the API has to offer natively without the developer needing to worry about building their own HTTPS requests. This allows rapid development and integration with BaseSpace data and a simple mechanism of discovering what the API has to offer.
The API uses the standard OAuth v2 protocol to allow secure access to user data while letting the user stay in control of what the App can and cannot access. When an App wishes to access a user data, it uses the API to initates a 'handshaking' process between itself and BaseSpace. The BaseSpace user is presented with a dialog that informs them of the data the App is requesting, the level of access to it, and the opportunity to permit or cancel the request. The OAuth2 process ensures safe and transparent data access between users and Apps.
Types of applications
BaseSpace offers supports for all major types of application platforms:
- Web - user interacts with a web site via a browser (potentially through a mobile browser)
- Desktop - a desktop program that runs on a user's computer
- Mobile - an app such as an iPhone or Android app
- Native - a program that executes within the BaseSpace infrastructure
Get started!
The following will cover all of the steps necessary to get started with developing a BaseSpace App.
Steps for developing your first App
This overview will walk you through some of the main steps to get you ready to start developing your app.
- Regardless of the type of app you'd like to develop, you'll need to Register as a developer on the BaseSpace Dev Portal and create a new application.
- Create an app in the App Dashboard
- Understand the resources exposed by the API by in the Data Model Overview.
- Determine the type of application you would like to create, either Web, Desktop, or Native.
- Refer to the Release Notes to keep up on changes to the API and the Developer Group to ask questions or provide feedback. You may want to subscribe to receive abridged daily summaries of the group to stay informed. Check the FAQ before posting though.
Choose a Platform for the App
Web App
Web apps are the most common types of apps on BaseSpace as they offer the quickest way for users to get started and derive value. They offer a secure environment that the user is already used to using without needing any upfront installation effort and with few concerns about cross-platform compatibility.
For web apps, BaseSpace offers a simple mechanism of getting access to user data we call App Triggering. In the My App control panel for your app you're able to select from which areas in BaseSpace your app may be launched including from a Project, a Sample, or an Appresult. Additionally, you may specify what level of access your app will need to these resources.
When the user launches a web app in BaseSpace, a dialog with this list of permissions will be displayed to the user.
The user is then redirected to your app with information about how the it was started and a simple means of getting to the granted data via the API. This is described in detail in the App Triggering guide which we urge you to look over.
Later, if your app requires more permission from the user to access other data in BaseSpace, it would need to follow the Obtaining Access Tokens Guide to make a new request for permission.
Once the user is authenticated, the next step is to use the Rest API or one of the SDKs to interact with the user's data in BaseSpace. The API and SDKs allow the developer to download data from BaseSpace, update Status for the user, report processing and error logs, and upload data back to BaseSpace. Use the API Reference as a go-to for detailed descriptions of each method. We have a few SDKs available including Java, Ruby, R, and Python. These guides will take a developer through the necessary steps to create a sample app.
Desktop or Mobile App
For visualization, analysis, or monitoring applications, native desktop or mobile apps often provide abilities unavailable to web apps.
You may wish to integrate BaseSpace data into an already existing Desktop app. In this case, the app would not launch from BaseSpace, instead it would simply use the API to access user data.
Although BaseSpace will not host your desktop/mobile app for download, you may offer it on your web site. In the My App control panel for your app, set the redirect_uri to your web site where you're offering the download or instructions.
Desktop and Mobile apps will need to request appropriate permission to user data by using the device code OAuth flow, this is slightly different from the standard web app OAuth protocol highlighted in the previous section.
Please refer to the non-Web based OAuth Flow in Obtaining Access Tokens.
Native App
Native applications are for developers who do not have a robust background in web development. In fact, developers use tools in the developer portal to create input forms and output reports for their applications. The application itself is a Docker image that is managed by BaseSpace, so a user will launch the app from BaseSpace and BaseSpace will determine the compute requirements, the machine to run the app on, and more!
Native apps automate a lotof the general REST API requests so that developers, for most simple apps, will never have to learn the REST API or any of the SDKs for BaseSpace.
Please refer to the Native App Overview for more information about Native applications.
Submitting an App for Publishing
Illumina no longer supports the submission and publication of applications for use by Illumina BaseSpace users. However, developers are still welcome to create and use apps for private use:
- An application that is owned by a user or workgroup with an enterprise subscription can be made available to all users and workgroups in the enterprise domain.
- An application that is owned by a user or workgroup in the public domain can be explicitly shared with other users by adding their email to the "Test User" list on the application details tab.
If you would like to discuss the development and publication of a potential application that fulfills an unmet need in omics, please contact Business Development at businessdevelopment@illumina.com.