Adding the First Endpoint to an API

Series: Building a REST API with Ruby
10 Apr 2014

Welcome back! For this part I am going to show you how we will add our first endpoint to the API. This will also introduce a few key concepts like mounting an API resource and routing. I will also cover adding our testing setup in this post, because of course we are doing TDD! But first, a quick background on what the API will do.

The API will be a very simple blogging/cms application, a venerable example :). When all is said and done, the API should have users, administrators, posts, tagging, and more. But, for the first API endpoint we will add a way to check the status. This will be a super simple endpoint that can be hit that will just return a 200 OK response so someone using the API will be able to know if the API is reachable.

First things first, lets add rspec so we can start writing our test for this endpoint. You can of course exchange these gems with ones of your choice like test-unit, but we will be using rspec throughout this series.

  • Add rspec, rack-test, and json_spec to the Gemfile
  • Then we will add a spec folder to the project and create the spec_helper.rb file.

What is going on here is pretty straight forward, but heres a quick rundown: We are requiring our application.rb file, then creating an instance of our API that tests will run against. The following block is a typical configuration block for rspec which you can read more about here.

  • Next add the folder api under the spec folder and add a file status_spec.rb. This will serve as a space to place all of our specs for the API endpoints.

If you are familiar with RSpec this should look pretty familiar. We are just using rack-test helpers to send a get request to the endpoint /status then expecting a 200 response and the json { status: ok }. This will of course return an error that the route can not be found since we have not yet made it.

  • Now that we have our spec all written up we can start working on the actual endpoint. First lets create the endpoint:

For this endpoint we are using a GET request and will not require any authentication. The namespace block will be the name of the resource of our endpoint, status. The desc helper simply allows us to add a description to the endpoint, which can easily be used to generate documentation (more on that soon) and overall adds clarity. The get block defines our request method and what should be run and returned, in this case simply JSON returning 200 OK.

If we run our specs now you will notice there is still an error about the missing route, this is because we still have to require the file and mount the endpoint into the API. To do so we need to add to our application.rb and boot.rb files to include our new endpoint.

You may notice that we now are using ActiveSupport::Configurable. This is a personal preference that I like for configuring common parts of the application but it is not required. You could just as easily accomplish this using the previous way we instantiated env and just keep using File.expand_path to create an equivalent root, whichever you prefer. Also, you will notice a method include_files which does just as you may expect and is just an easy way to require additional files. In this case all of our public API files including status.rb that we have created.

And finally we mount the API endpoint into our API inside of the app/api.rb file.

Now when we re run the specs you should get a nice all green! Success, we have added our first endpoint! You can also now run rackup in your terminal and go to localhost:9292/status to see your API in action. Don’t forget to check out the source code for the whole project by clicking the Github icon above!

comments powered by Disqus