Introduction to the API tutorial

Who is this for?

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?
• Try this: Use Postman to talk to the API
• Parts of an API request
• The path
  • Try this: Enter the Path in Postman
• The method
  • Try this: Enter the method in Postman
• Headers
  • Try this: Enter headers in Postman
• The body
  • Try this: Enter a request body in Postman
  • Try this: Send your request
• The API responds to you
• Optional: Query parameters
• Try this: Enter optional parameters in Postman
• Next step
• In a nutshell...

What's covered in this tutorial?

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.

Overview of APIs

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

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.

How do clients talk to the API?

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.

Try this: Use Postman to talk to the API

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.

Once you're familiar with the API, you can also consult our Python library and our R library. We also host various recipes and tutorials in the okAPI repository.

Before we go into the specifics of an API request, let's install Postman.

📘

System requirements

Postman requires Chrome or OS X to run.

To get started:

1. Go to the official Postman website.
2. Click Download.
3. Once your download has finished, install and 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.

Parts of an API request

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:

• The path
• The method
• Header(s)
• The body

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

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.

In the screenshot above, you can see the selected path for the AWS US deployment of the Platform, https://api.sbgenomics.com/v2/projects.

If you are using the Platform on AWS EU, use the corresponding path from the Path for Seven Bridges Platform EU section.

Try this: Enter the Path in Postman

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

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 GET request to list all of the projects you belong to.
• POST - This creates new information. For example, you can use a POST request to create a new project.
• PATCH - This updates a specific part of previously stored information. For example, you can use a PATCH request to modify a portion of a project member's permission.
• PUT - This overwrites previously stored information. For example, you can use a PUT request to completely overwrite a project member's old set of permissions.
• DELETE - This deletes information. For example, you can use a DELETE request 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.

Try this: Enter the method in Postman

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 GET request.

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

Headers specify the metadata for an API request. They provide required operating parameters for the API request.

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.

1. Required headers for all API calls are listed in the API Overview. These include:

2. In the request page HEADERS section, you'll see some of the headers for Seven Bridges API requests, as shown below.

You can see an example code snippet on the right side of the documentation page, provided in the language of your choice (python by default for most of the requests).

To change the request language, click on the icon of the language in which you wish to see the request. If you cannot find the associated icon, click on the three dots on the rightmost side of the LANGUAGE section, and select the language you with to use.

👍

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.

Try this: Enter headers in Postman

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 application/json
• Accept - enter application/json

Enter them into the Headers tab, as shown below.

Now, you're ready to enter the body of the request.

The body

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 POST, PUT, or 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.

Try this: Enter a request body in Postman

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.

Try this: Send your request

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.

The API responds to you

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.

Optional: Query parameters

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 id or name.

The API documentation includes details on accepted parameters for each request, as shown below for the request to list all your projects.

Try this: Enter optional parameters in Postman

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 https://api.sbgenomics.com/v2/projects.

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.

Next step

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 a nutshell...

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