Learn Parabola

Welcome to Learn Parabola! You'll find comprehensive guides and documentation to help you start working with Parabola as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

WTF is an API? I'm scared 👻

An API is an Application Programming Interface. If you are you familiar with the Internet of Things, or a future where all electronic devices talk to each other, API's are the foundation of how those electronic devices communicate. It is the language that devices, computers, and all sorts of technology use to share information.

You have most likely seen the word API sprinkled on websites in "For Developers" sections. API's give users access to underlying data and functionality of a web application. An API is typically the most robust way to access an application's functionality.

👍

API's are a language that computers use to share information

For example, you can see all of the songs on Spotify in their app, which is an example of a Graphical User Interface or a GUI. You'd need to access their API to pull the data out of their application. Let's say you're trying to run an analysis on the most popular reggaeton songs in Latin America. You'd want to access all of Spotify's data in order to analyze it. API's are the magical thing that will save you from manually writing down thousands of titles of reggaeton songs.

When engineers use code to access data via an API, you get the benefit of reusability, allowing you to access the most up-to-date data at any time. Unfortunately, API's generally require coding skills to access (unless you're using Parabola).

Anatomy of an API request

To get started, let's walk through the anatomy of an API request.

The request URL

API requests are made using a request URL. These will look a lot like the URL's that you are used to seeing as you browse the Internet. Similar to a website URL, a request URL asks the API for a specific resource or list of resources.

For example, let's try to pull a list of Kanye's top 10 singles from Spotify. To start, we can request a list of all artists on Spotify.

GET https://api.spotify.com/v1/artists

This is useful, but we need to access the album data, not just the artists. Looking at Spotify's API docs, there is another endpoint to pull all albums for a specific artist.

Let's add in the artist ID and request the albums. From the last request, we know that Kanye's ID is 123

GET https://api.spotify.com/v1/artists/123/albums

The response may look like this:

{  
   "albums":[  
      {  
         "name":"My Beautiful Dark Twisted Fantasy",
         "id":1,
         "type":"full",
         "release_year":2010
      },
      {  
         "name":"The College Dropout",
         "id":2,
         "type":"full",
         "release_year":2004
      },
      {  
         "name":"Homecoming",
         "id":3,
         "type":"single",
         "release_year":2008
      }
   ]
}

Now that we have the list of albums, to reach our goal, we want the top 10 singles. To do so, we can rely on request parameters that Spotify's API allows.

Request or query parameters

Think of request parameters (also known as query parameters) as filters that you can add to your request URL to specify the types of results you'll get back.

Request parameter is attached to a request URL after a question mark (?) and multiple are combined with ampersands(&).

Adding in a filter for album type and limiting the number of returned albums looks like this:

GET https://api.spotify.com/v1/artists/123/albums?type=SINGLE&limit=10

Notice how we have two request parameters combined by an ampersand(&) and starting with a question mark(?).

This query requests albums by Kanye, only accepting those of the type SINGLE and limiting the results to the first 10 returned.

Types of requests

There are 4 different types of requests:

GET
A GET request asks the API to respond with something that it has, most often data. You can ask for specific information about one item or a group of items based on the endpoint and parameters.

Notice that the URL's in the above examples all have GET in front of them. When making a request to an API in code, you need to specify the request verb. When using Parabola, that is not necessary.

POST
A POST requests the API to create something new. In our Spotify example, a POST would request to add a new song, artist, or album.

PUT
A PUT requests the API to update something already present. A PUT request updates the information about an existing entity within Spotify.

For example, after Kanye released the The Life of Pablo album, he later updated the songs in his album to invite listeners to experience the evolution of his music over time. Using a PUT request, Kanye kept the same track list, preserving the play count and other metadata, while updating only the musical files.

DELETE
A DELETE requests the API to delete something that exists. For example, when Taylor Swift claimed to be making a stand for small artists, she deleted all of her music from Spotify. Using a delete request, Taylor removed all of her albums in Spotify.

Request VerbResults
GETRequest a specific resource, or list of resources
POSTSend data to an API to create a new resource
PUTSend data to an API to update an existing resource
DELETERequest a specific resource to be deleted

Updated 2 months ago

WTF is an API? I'm scared 👻


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.