Building and testing a simple REST api with Elixir & Plug
So you’ve been wondering how to build rest APIs using Elixir and Plug whether it’s for a frontend application or a microservice ? We are going to build one which will return JSON responses and test it.
Installation
Before starting anything, you have to make sure you have Elixir and Mix working correctly on your machine and then we will use a simple and basic boilerplate in order to avoid all complications.
We will call our application movie_api_plug, so we will have to run these commands below:
git clone --depth=1 https://github.com/imhassane/elixir-plug-rest-boilerplate.git movie_api_plug
mix deps.get
Your project architecture should look like this now:
What are these directories for ?
This architecture is just a default configuration, you can set up your own if you want but for now, let’s suppose you don’t need to do it.
The config directory will contain your environment variables depending on the current environment. As we are on a development environment, the dev.exs file will be imported in the config.exs file.
The routes directory will contain all your api routes definitions, you are not required to use the api_router.ex file, it’s just here to give you an example on how the routes work.
The test directory will contain all your tests.
These are the only directories that interess us for now. For this api we will only use the routes directory and the lib/router.ex file.
Let’s add our routes
Your api will have to listen to certain url and return json response or whatever kind of response you want. By default, the project is configured to send json responses with the Jason module.
Defining the base url for our api
Open the lib/router.ex file, you’ll find this line below
forward "/api", to: Routes.ApiRouter
This means that whenever the url address start /api , we will use the Routes.ApiRouter module which will contain all the routes definitions.
So we will define our own now, as we are creating a movie API we will listen for all the urls starting with /movies . Let’s add a new line just below:
forward "/movies", to: Routes.MovieRouter
Let’s define our routes
Open the lib/routes/api_router.ex file and you will see that some routes have already been initialized. These are here just as examples. We will create our routes definition in the same directory in a file named movie_router.ex and add this content in it.
So, we have a movies list which contains our movies list. In real situations, you’d use a database but this is not one, we are just training here.
Then you have two functions without a name but starting with a get which means we will listen to get requests to the address /movies/ and we return the movies list and to get requests to the address /movies/:id and we return the movie with the ID :id.
Other options
To listen to post requests, you can replace get by post . The data passed via post requests will be available within the conn.body_params variable and this is true for put and delete requests.
Let’s test our API
By default, your api will listen to the port 8000, you can change it by going to the config/dev.exs file and change the port variable.
Open you favorite browser or postman and go to this address: http://localhost:8000/movies/ and voilà! You shall see all your movies.
If you go to to the address: http://localhost:8000/movies/1 , you’ll receive the first movie of our basic database :) :).
You can test the API with unit tests too. Create a new file named movies_test.exs in the test directory. It will contain the following test instructions.
It basically calls our two urls and check if the response status is equal to 200 which means that everything went well, you can now run mix testto see whether or not your code is correct. You’ll get the following result if everything went well.
How come we have 6 test when we’ve written only two ? :) :), by default some tests are also written for then Routes.ApiRouter that we’ve seen above. You can check it to see how you can write tests for post , put and delete requests.
If you’ve made it so far, it means you’ve written your first API. Have fun writing your future APIs with Elixir and Plug.
