REST APIs are everywhere around us. Software engineers use them to develop backend logic, and data scientists use them to deploy machine learning models. In this blog you’ll learn how to make a REST API with R and the plumber package.
Introduction to REST APIs
REST stands for “Representational State Transfer”. In simpler words, it represents a set of rules that developers follow when creating APIs. The most important rule is that you should get a response (data) whenever you make a request to a particular URL.
The request you make consists of four components:
- Endpoint – a part of the URL you visit. For example, the endpoint of the URL https://gerinberg.com/predict is /predict
- Method – a type of request you’re sending, can be either GET, POST, PUT, PATCH, and DELETE. They are used to perform one of these actions: Create, Read, Update, Delete (CRUD)
- Headers – used for providing information (think authentication credentials, for example). They are provided as key-value pairs
- Body – information that is sent to the server. Used only when not making GET requests.
Most of the time, the response returned after making a request is in JSON format. The alternative format is XML, but JSON is more common. You can also return other objects, such as images instead.
R allows you to develop REST APIs with the plumber package. You can read the official documentation here.
It’s easy to rewrite any R script file to an API with plumber, because you only have to decorate your functions with comments. You’ll see that in the next section.
Develop a Simple REST API with R & Plumber
To start, create an empty R script file. You’ll need a couple of packages:
- plumber – to develop the API
- dplyr– to filter datasets based on certain fields
- gapminder – the dataset that we will use for the API.
You can place two comments for specifying API title and description. These two aren’t mandatory, but it’s good to document the API call. Let’s create our endpoint now.
Endpoint /countries
The idea behind this endpoint is that it should return countries and their respective data after a couple of filters are applied. To be more precise, this endpoint accepts parameter values for continent, life expectancy, and population. Value for continent must be exact, and values for the other two parameters filter data so that only rows with greater values are returned.
If you want to do things right, it’ll require many comments, as you’ve seen previously. It’s a good practice to write a short description, list the parameters, and it’s mandatory to specify the request type and the endpoint.
Below the comments, you’ll place a function that performs the necessary logic and returns the results.
Let’s think about the endpoint parameters for a second. You’ll need:
- continent – column continent
- life expectancy – column lifeExp
- population – column pop
All three are optional, and you can do the filtering based on the parameter values with the dplyr package. This endpoint will return data for the most recent year only, which is 2007.
Here’s the complete code so far:
If you were to run the API now, this is what you’d see:
The endpoint on the bottom of the image (blue box) is clickable. Clicking on it expands a new section:
You can click on the “Try it out” button to make a request straight from the browser. As you can see, the parameters have some values filled in already. Once you click on the “Execute” button, the response will be shown at the bottom. Here’s how it looks like for the default parameters:
Great, you have created your first endpoint! It takes data in and returns data out. You can also return other outputs like an image.
Conclusion
In this blog post you have learned what REST APIs are, what’s the use of the plumber package, and how to use it to build basic APIs in R.
APIs in R are commonly developed for exposing the result of machine learning models. Another option to share your data analysis results is to create a dashboard or a report with Shiny or Markdown.