You'll find this tutorial especially helpful if you have only used the visual interface of the Seven Bridges Platform but would like to explore beyond the limits of the visual interface.
You've signed up for the Seven Bridges Platform. Now what? You start by accessing the visual interface of the Platform. You find the visual interface adequate for most of your needs. Then, you're tasked with a time-intensive task—such as uploading or copying hundreds or thousands of files—and you wonder, is there a way to automate this?
Yes, via the API (Application Programming Interface).
This tutorial contains sequential directions, so we recommend that you read everything in order.
However, if you're ready to work with the API on your own, you can visit our API Overview page.
On this page:
- What's covered in this tutorial?
- Overview of APIs
- The Seven Bridges API
- How do clients talk to the API?
- Parts of an API request
- The API responds to you
- Optional: Query parameters
- Next step
- In a nutshell...
We'll be covering two topics in this tutorial. First, we'll provide background information on what an API is and how to use it. Second, we will walk you through a making a simple API call to list all of the projects associated with your Seven Bridges Platform account by using Postman.
We've structured this tutorial so that the information and walkthrough portions are staggered. That is, after most information sections is a walkthrough portion, Try this. We've highlighted the titles of the walkthrough portions in red to make them stand out.
The Application Programming Interface (API) is a means to interact with our server and its data. An API is a programmatic interface for accessing and manipulating resources: just as the Platform's visual interface allows you to create projects, run tasks, and manage project members by clicking buttons and entering data to web forms, the Application Programming interface allows these procedures to be carried out programatically. This means that a computer program can now create projects, run tasks, manage project members, and so on. It does this by issuing requests to, and returning data from, the servers.
You can interact with the API using various clients, such as an API client like Postman, a programming language like Python, or through your terminal by using a command line program like cURL. These clients use the API to access the data. Then, the client displays the data pulled by the API to the user.
For instance, if you use Postman as your client, Postman will use the API to pull data. Then, Postman will display the data to the user.
We'll learn more about how to use Postman with the Seven Bridges API below.
The Seven Bridges API can be used to integrate the Platform with other applications, and to automate most procedures on it, such as uploading files, querying metadata, and executing analyses. The API uses the Representational State Transfer (REST) architectural style to read and write information about projects on the Seven Bridges Platform. This means calls are made using HTTP.
You're probably familiar with HTTP as the part of a web page's URL. In fact, HTTP is the foundation behind data communication on the World Wide Web—it's a protocol for fetching data from web servers and allows applications to talk to one another on the web. So, when you enter the "http" in the beginning of an URL into a web browser, you're telling the browser to talk to the server and that the following commands (the rest of the URL) uses HTTP protocol.
When you use a client to talk to the API, you'll be using HTTP.
Clients use the API to make a request of the server. Then, the server returns a response via the API to the client. Depending on the type of request, the response is either the requested data or a confirmation that the requested action was performed.
While you can use various clients to interact with the Seven Bridges API, we recommend using Postman to learn how the API works and how easy it is to use our powerful API. Postman, a free API-request client, has a visual interface you can use to type out your HTTP requests. It also returns the response in the same visually-pleasing format of the examples in our API documentation.
Using the API
Postman is a great tool for users to learn how the API works as well as for developers to test the API. However, to take full advantage of the automation which makes the Seven Bridges API so powerful, we recommend using R, Bash, or Python.
Before we go into the specifics of an API request, let's install Postman.
Postman requires Chrome or OS X to run.
To get started:
- Go to https://www.getpostman.com/.
- Then, choose between Postman for Chrome or Postman as a Mac App and follow the installation instructions.
- Once your download has finished, launch Postman, as shown below.
You can use various clients to talk to the Seven Bridges API. This tutorial provides examples and directions specific to using Postman, but you can also take away major points and apply them to other clients.
Time to talk to the API! But how?
You need to use Postman to use the API to make a request of the server. Then, the server returns a response via the API to Postman. Let's first walk through the different parts of an API request. We'll return to responses below.
In basic terms, an API request consists of four parts:
You need these parts to make the request work properly. Generally, you need all four parts. However, certain types of requests, such as
GET requests do not have a body. We'll learn more about this in the section on methods below.
We'll learn about query parameters, an optional fifth part of an API request, in the section on modifying your API request below.
The path specifies the object for the request. Basically, the path is a URI which points to a unique resource on the Platform that will be the recipient of the request. For example, the path
https://api.sbgenomics.com/v2/projects specifies projects on the Platform as the object of the request.
URI versus URL
A URI (Uniform Resource Identifier) identifies a physical or abstract resource. It can be a name or locator, or both.
In fact, it's related to a more familiar concept: the URL. A URL (Uniform Resource Locator) is a kind of URI which identify the location of a resource. For instance, a URL can actually locate the resource by describing its network location.
We've cultivated a list of API requests in the API documentation on our Knowledge Center, as shown below. You can click on API Reference in the left sidebar to see all the requests you can make.
On each of these pages, you'll see the path at the top of the page, as shown below.
Here, there are two tabs you can select: Path for Amazon Web Services users and Path for Google Cloud Platform users. Select the option for the Platform you use.
Seven Bridges Platform deployments
The Seven Bridges Platform was originally deployed on Amazon Web Services (AWS). On January 15, 2016, the Platform was deployed on Google's cloud infrastructure, the Google Cloud Platform (GCP).
To determine which cloud provider you're using, look at the URL you use to access the visual interface. If the url is https://igor.sbgenomics.com, you are using the Platform on AWS. If the URL is https://gcp.sbgenomics.com/, you are using the Platform on GCP.
To learn more about the differences between AWS and GCP for Platform users, read our blog post.
In the screenshot above, you can see the path you should use on the Google Cloud Platform,
Below, you can see the path for Amazon Web Services for the same request.
As you can see, the path you should use on Amazon Web Services is
Once you've located the path, paste it into the Enter request URL box on Postman, as shown below. For this tutorial, we'll be making a request for projects. Specifically, to get a list of all projects of which you are a member.
Now you've specified the path. Next, we'll set the method.
The method specifies the type of request. It describes the type of action that you want to take via the API.
Possible methods for the Seven Bridges API are:
GET- This retrieves information. For example, you can use a
GETrequest to list all of the projects you belong to.
POST- This creates new information. For example, you can use a
POSTrequest to create a new project.
PATCH- This updates a specific part of previously stored information. For example, you can use a
PATCHrequest to modify a portion of a project member's permission.
PUT- This overwrites previously stored information. For example, you can use a
PUTrequest to completely overwrite a project member's old set of permissions.
DELETE- This deletes information. For example, you can use a
DELETErequest to delete your project.
We've used colored buttons next to the API title in the sidebar and the documentation page to highlight the method, as shown below.
Since we want to use Postman to ask the API to list all of the projects you are a member of, this is a request for information. So it's a
As you can see above, the method is also shown next to the page title, List all your projects.
To enter the method, click the GET button next to the path. This will pull up a drop-down menu, as below. Make sure GET is selected.
Now you've selected the method. Next, we will specify the headers.
Headers specify the metadata for an API request. They provide required operating parameters for the API request.
In the picture below, you'll see some of the headers for Seven Bridges API requests.
The required headers for each API call are listed in two places, as detailed below. Be sure to include all required headers for your API request to work.
- Required headers for all API calls are listed in the API Overview. These include:
- Required headers for individual requests are listed in the relevant documentation page under the Request section, as shown below.
Almost all API requests will require your Seven Bridges authentication token. This acts as a security measure regulating your access to your projects. Learn more about obtaining your authentication token.
First, locate the required headers in our API documentation. Then, click on the Headers tab in Postman, and input the headers.
For the API request to list all your projects, you need the following headers:
- X-SBG-Auth-Token - enter your authentication token
- Content-type - enter
- Accept - enter
Enter them into the Headers tab, as shown below.
Now, you're ready to enter the body of the request.
This specifies the data you wish to send to the Platform. In the case of a
GET request, where you're obtaining information, there would be no body. However, when you send data to the Platform via a
PATCH request, you will need to provide the data in the body of the request.
In our API documentation, we've provided the required keys and values for each request body, as shown below for the create a new project request.
For each API request with a body, we've also provided an example request body in the documentation, as shown below.
The API call to list all your projects is a
GET request. This means the request doesn't have a body because you are asking for information from the Platform rather than sending data to the Platform.
Now that your request is fully prepared, you can send your request in Postman by clicking the blue SEND button in the upper right hand corner, as shown below.
Now that you've successfully sent your request to list all of your projects, Postman will display a response to your request, as shown below.
As you requested, you can see a list of all the projects of which you are a member. Your
GET request returns the
"href" (path) of each project, the
"id" (project owner and short name of the project), and the
"name" (project's name, as displayed on the visual interface).
If you run into an error, you'll receive a 4 digit error code and information specific to the Platform in the body of the response.
Congratulations! You've successfully completed an API request to list your projects. At this point, you can continue to our API documentation to test out other requests. Or, you can continue on this page to find out how to further customize your API requests.
Each Seven Bridges API request can take one or more optional query parameters which further filter your request. For instance, the
fields parameter is accepted by all requests. With the
fields parameter, you can specify that only certain fields are returned in the response body, such as
Let's return to our request to list all of your projects and try to add the
fields parameter to our request in Postman. We want the API request to only return the path (
href) of the projects.
Input the path, method, and headers as you did above.
You can add query parameters by typing
? followed by the name for the parameter (ex:
fields) followed by
= and a value (ex:
href). In the example below, we've appended
?fields=href to the end of the path
Click Send when you've finished modifying your API request.
As you can see below, the response returned by your modified request only contains the paths for each project.
And, that's it! You've not only completed a successful API request, but you've also modified it by specifying optional query parameters.
In this tutorial, we used Postman to learn how the API works. However, to take full advantage of the automation which makes the Seven Bridges API so powerful, we recommend using R, Bash, or Python.
For more information, you can also consult okAPI, our repository of API recipes, or the Seven Bridges Python bindings library, which provides a set of Python terms for interacting with the Seven Bridges API.
In this tutorial, you learned:
- An API is a way to interact with our servers and its data.
- The four parts of an API request (the path, the method, the headers, and the body)
- How to modify an API request with query parameters