We are happy to announce the introduction of API-driven App launch capabilities on BaseSpace. We are now extending the BaseSpace API to include app launch, so that with a call to a RESTful API endpoint, you can launch a BaseSpace app on your data. With the new feature in the API, you can now:
- Configure and launch multiple Apps in succession or in parallel using a script, this ensures consistency of configuration and reduces the possibility of human error through manual launch
- Automatically launch Apps in the background, without direct intervention by a human user. This allows the possibility of unattended sets of app launches, such as apps that launch in the middle of the night as soon as sequencing data is ready, rather than waiting for a manual launch
- Create scripts to automate testing of your app for developers
The apps are launched in exactly the same underlying BaseSpace environment as the web UI, so you can check the status of API-launched apps and look at generated reports through the web UI. In addition, the ability to launch the apps on a locally configured machine or a local virtual machine are also supported via this API.
There are several ways to make use of the API-driven app launch. One is to use the API directly, using any HTTP compatible toolchain such as curl or the Chrome plugin Postman. The documentation for using this API can be found in the API Reference. To make this process more convenient and hide the details of authentication, we have also exposed the relevant APIs as part of the Python SDK. You can find details of the Python SDK method here.
Example App Launch Script
To demonstrate the power of API-driven app launch, we have made available a set of prototype tools to automate some of the analysis needs of a sequencing facility using BaseSpace. These tools are open source and available on github at https://github.com/basespace/LaunchSpace, The scripts are designed to be run on a Unix host using cron, the command scheduling application that comes with all modern Unix flavors. Cron can run command line tools at regular intervals so that a server machine can be periodically polling BaseSpace to look for the arrival of new data.
When that data arrives, the tools configure and launch an app run using the BaseSpace API. Further tools, also run with cron, poll BaseSpace to keep track of that app as it runs to completion and then check and download the results. All of this happens without intervention from the user, as cron tools continues to work on the samples as they arrive in BaseSpace. Further command line tools are provided to keep track of the status of app runs and intervene in problem samples.
The scripts are written in Python and make use of the BaseSpace Python SDK for interaction with the BaseSpace API. The github repo has been carefully documented so that you should be able to not only use them as they are, but also extend and modify them for your own needs. The developers of the tools will also be monitoring the BaseSpace forums (https://groups.google.com/forum/#!forum/basespace-developers) to answer any questions you might have or help with using and adapting the tools to your needs. For more information on these tools and to try them for yourself, go here.
API Rate Limiting
Along with this new API we are also introducing the concept of API Rate limiting. While any API can have a limit, we are currently focused on the App launch API. You will notice new http headers being returned on this API described below and in more detail API Reference:
- X-RateLimit-Policy – The name of the policy/rule that applied for this API request
- X-RateLimit-Limit – For the applicable policy, the maximum number of requests that the user is permitted to make in the current rate limit window before usage is restricted
- X-RateLimit-Remaining -The number of requests remaining in the current rate limit window
- X-RateLimit-Reset – The UTC date/time when the rate limit usage for this policy will be reset
App Launch API Restrictions
- API Rate Limiting: There are limitations on how many requests can be made to the app launch API for each user.
- Only Native applications can be launched using this API: This is primarily because Native applications have a pre-defined set of input fields that a user may configure, whereas non-Native applications (Web/Desktop) are more open-ended.
- Only free applications can be launched with this API.
- Only Apps that you have access to and that are in Beta or Published state can be launched and run on our platform.
- Apps that are in development can use this API to send to your local agent, but cannot be run on the platform until they are in Beta or Published