This post will show how to build a REST API with Elixir and Phoenix Framework. The focus will be providing CRUD (create, read, update, delete) endpoints for a model which is persisted to a Postgres database backend. I should warn you; this is a trivial example. But, hopefully, it helps you move forward in your Elixir and Phoenix journey.

Side trip: I’m coming from using Akka and Scala for building REST APIs. Similar to Akka, Elixir has underpinnings to Erlang. I’m a fan of the Erlang model for asynchronous processing. How could a person not be? Well, distributed, asynchronous systems are difficult to debug, but I digress. As I said, I’m still a fan of this model for being able to scale. And it’s nice to get back to loose type language in Elixir.

First, Install Requirements

1. Install Elixir (Details: http://elixir-lang.org/install.html. Follow these instructions, because Erlang is included. I used homebrew to install)
2. Install Hex by running in a terminal:
    
   Elixir Hex install

   mix local.hex

3. Install Phoenix:

   mix archive.install https://github.com/phoenixframework/archives/raw/master/phoenix_new.ez

4. Maybe install Node.js as dependency for asset management. See “node.js” section here http://www.phoenixframework.org/docs/installation
5. Install Postgres. I’m using Postgres.app on a Mac. Make sure the postgres user has a password of postgres

Second, Let’s Build

1. In a terminal window, create the baseline app by issuing:
    
   New Phoenix Framework app

   mix phoenix.new api_spike

   Name api_spike anything you want. You may be asked to install dependencies. I say Yes! (Ref: step 4 in the first section above)

2. Go into your new api_spike directory:

   cd api_spike

3. Create the Postgres database to use for the app:

   mix ecto.create

   Background: check your Postgres settings in conf/dev.exs file if this doesn’t work. Default connection uses username postgres with a password of postgres. See Step 5 above.

4. Generate a Model and get a bunch of other stuff for free:

   mix phoenix.gen.json User users fullname:string email:string age:integer

   Note: the phoenix.gen task is specifying json. You can also build HTML views if you use phoenix.gen.html. This is what messed me up when I was first trying Phoenix.

5. Open web/router.ex file, uncomment api scope and add a new line for newly generated UserController from the previous step. It should looks like this:
    
   Phoenix REST API

    scope "/api", ApiSpike do
    pipe_through :api
    resources "/users", UserController, except: [:new, :edit]
    end

Update the database by issuing:

mix ecto.migrate

6. Done. Start Phoenix!

   mix phoenix.server

Third, Try it Out

We can now make some calls to perform CRUD operations, such as create:

	
curl -H "Content-Type: application/json" -X POST -d '{"user": {"fullname": "Todd", "email": "phoenix@apiexample.com", "age": 19}}' http://localhost:4000/api/users

And now reads:

curl -H "Content-Type: application/json" http://localhost:4000/api/users

curl -H "Content-Type: application/json" http://localhost:4000/api/users/1

update:

Phoenix framework update REST call

curl -H "Content-Type: application/json" -X PUT -d '{"user": {"fullname": "Not Todd", "email": "phoenix@apiexample.com", "age": 43}}' http://localhost:4000/api/users/1

And finally, delete:

curl -H "Content-Type: application/json" -X DELETE http://localhost:4000/api/users/1

Eat, Drink, Dance and Be Merry

I did call this post a how-to quick start for a reason. It’s intended to help get you started with building REST APIs with Phoenix and more comfortable with Elixir. If you need any more detail, just connect with me on Twitter or leave a comment below.