How-Tos: Using REST APIs

The whole internet is a request away

Have you ever been itching to build something cool? An APP that uses data from wearables to let people know being a coach potato all day is not healthy, or a website-based game that allows users to connect to random users on the internet over a silly fitness challenge?

This guide will show you how you can get started playing with a REST API to build all these cool things!

Definitions (For the true g̶e̶e̶k̶s̶ )

REpresentational State Transfer - Application Programming Interface (REST-API) may sound like some fancy term but after all, it's just a specific style of API that uses HyperText Transfer Protocol (HTTP) to send and receive data over the web.

HTTP allows web servers to communicate (send and receive data) with web-clients (you). They do this in requests. Requests typically come in the following types (although there are more less commonly used ones):

• GET- The name stands for itself: You try to get some data from the server
• PUT- This type typically allows you to update data on the server
• DELETE- This type allows you to delete data on the server (hence its name)
• POST- This type allows you to send new data to the server

Any REST API out there must be defined in such a way that it:

• It is Client - Server Bound. Meaning there's always a client (you requesting for the song on Spotify) and a Server (where the song is from)
• There are no states. This means there are simply no history on what requests were made before. Thus another request is a new request to the server
• Cacheable. This means the data from the request can be stored (temporarily) on either user or server sides
• Layered System. The REST API is deployed on multiple servers, perhaps the actual API on one and storing of one in another.
• Uniform Interface. The API must have a uniform style and formatting. Our API (Terra) takes this constraint very seriously. When you are familiar with one of our data getting endpoints, every other follow the exact same format. This allows developers to simply reuse parts of their codes.

TLDR (for those that can't be bothered): REST API's allows you to do requests such as "GET", "POST", "PUT", "DELETE" and etc. to servers to get and receive data.

Usage

Best way to learn how something works is to play with it. Thus, let's start playing with an API. We will make a request to an API endpoint and see what we get out of it. Typically, this can be done through CURL. However there are other ways to do this programmatically with built-in libraries. For example, python allows you to make these requests easily through a library called requests.

For this example, I will be using Terra API's daily endpoint. This endpoint allows you to get data for a user that has authenticated successfully through us.

API endpoints will always be documented on the API's docs. Typically in the form <domain>/<path> : <https:api.tryterra.co=>..

If you go to the docs page, you will see that the request also requires a few "Query Params" and "Headers".

• Query Params are simply the parameters that exist after the ? in the request url. For example, in https://api.tryterra.co/v2/daily?startDate=2022-03-04, startDate is a query param with the value 2022-03-04.
• Headers are parameters that are included in the request. These represent "metadata" of the request.

Filling in these query params and headers are easy with the requests library:

The user_id is a unique identifier for my account that is generated by Terra upon successful authentication.

<MY DEV ID>, <MY X API KEY> are simply credentials I have from signing up to Terra.

Upon executing this code, I get the following json payload:

This data simply represents the data for that one day (2022–03–01) for me. You can now take this data and parse it, and build whatever you wish with it!

Master it

The example is simple, but you can extrapolate a lot from this. Imagine using the API to its full potential (getting sleep, activity, nutrition data as well), or using other REST API's out there: Spotify's, Twitter's, or (for the more advanced ;)) Google's.

You can make requests to any REST API on the web now using a similar structure as shown here. Perhaps they will have different query parameters or headers, or even a different HTTP request type than get. You may also choose to use another language than python: javascript provides the "node-fetch" library for this, swift provides a built in URLRequest type to make requests, java provides the "okhttp3" library, or for those preferring to have a user-interface for testing : Postman is a very friendly tool for this!

The possibilities at this point is endless. You can make whatever you want with the vast variety of REST API's out there!