This month I tried to improve. I interviewed friends in the industry and consumed some great content. Here’s what I learned:

1. Prepare good questions

Ideally, 1:1 meetings should be driven by the report. But, in my experience, most people do not prepare and are not comfortable driving their 1:1s. If that’s the case, the manager must be proactive.

In preparation, I spend a little time before each 1:1 thinking about questions I’d like to ask. Here are some example:

• What is worrying you most at the moment?
• Did you see the bit about AWS lambdas at the engineering all hands on tuesday?
• Do you think there’s anything I’m missing about our current projects? Anything you think I don’t understand fully?
• Have you spent much time pairing with Ben? If so, how was it?

These questions are useful to fall back on when conversation isn’t flowing naturally.

Preparing questions improved my 1:1s significantly. It shows the person I care and I’ve thoughts about them and I’ve put some effort into the meeting, so they should too.

2. Keep notes

In the past I haven’t taken notes in 1:1s. It’s extra effort and I felt it would distract me from the conversation. My research told me I was wrong so I experimented with keeping notes.

I found note taking helps me focus on what I’m hearing and retain information. It also demonstrates that information exchanged in 1:1s is important. Meeting aren’t jollies where we chat and forget about it. Keeping notes allows me to refer back and record actions.

To minimise the overhead, I’m using a very light weight Google Doc which looks like this:

Google Docs has a nice feature which auto populates the meeting. I typically do this 5 mins before the meeting whilst thinking about questions to ask. I add those questions at the top and fill out meeting notes during the meeting.

3. Circle back to previous 1:1s

Having a note system in place allows me to circle back. I try not to be too ridged about it but make an effort to review past 1:1 notes & actions.

1:1s have two main benefits - strengthening relationships & making improvements. Following up on actions is how we make improvements. It also builds trust by demonstrating that things raised during 1:1s actually get addressed.

4. Enjoy 1:1s!

I never dreaded 1:1s but I can’t say I was excited about them. Especially when I was busy I thought time could be better spent elsewhere. I’m sure that energy was apparent to the other person.

To improve, I made an effort to look forward to each 1:1 as an opportunity to connect with the person and learn. I tried to listen attentively and bring positive energy.

Harry Stebbings, podcaster and VC has a quote that’s a little over the top but helps put my in the right frame of mind: “go into every meeting saying, I want this to be that person’s best meeting, and I’m gonna fucking bring it”.

I’m enjoying 1:1s more because I’m actually learning things about the project and uncovering things for further investigation.

Results of the experiment

After a month, here are the results of my experiment:

1. I enjoy 1:1s more (and think my reports do too).
2. 1:1s feel less stilted and I’m improving relationships with team members.
3. I’m learning more about our projects & getting useful feedback.
4. I’m having deep conversations and actually solving problems. 1:1s have become productive! One afternoon I had back to back 1:1s and discussed our release process, in detail, with both engineers. I came away with an action plan for how to improve things.

1. Creating a Rails API Project and Routing
2. Basic Controller and Models
3. Building a POST Endpoint
4. HTTP Status Codes
5. Active Record Validations
6. Destroy Controller Action
7. Exception Handling in Controllers

1. Creating a Rails API Project and Routing
2. Basic Controller and Models
3. Building a POST Endpoint
4. HTTP Status Codes
5. Active Record Validations
6. Destroy Controller Action
7. Exception Handling in Controllers

1. Creating a Rails API Project and Routing
2. Basic Controller and Models
3. Building a POST Endpoint
4. HTTP Status Codes
5. Active Record Validations
6. Destroy Controller Action
7. Exception Handling in Controllers

1. Creating a Rails API Project and Routing
2. Basic Controller and Models
3. Building a POST Endpoint
4. HTTP Status Codes
5. Active Record Validations
6. Destroy Controller Action
7. Exception Handling in Controllers

1. Creating a Rails API Project and Routing
2. Basic Controller and Models
3. Building a POST Endpoint
4. HTTP Status Codes
5. Active Record Validations
6. Destroy Controller Action
7. Exception Handling in Controllers

1. Creating a Rails API Project and Routing
2. Basic Controller and Models
3. Building a POST Endpoint
4. HTTP Status Codes
5. Active Record Validations
6. Destroy Controller Action
7. Exception Handling in Controllers

1. Creating a Rails API Project and Routing
2. Basic Controller and Models
3. Building a POST Endpoint
4. HTTP Status Codes
5. Active Record Validations
6. Destroy Controller Action
7. Exception Handling in Controllers

Generating a controller

In part 1 we added a route for GET /books. The next step is to add a controller for it. To do that we can use the Rails generator, via the command line we can do:

$ bin/rails g controller BooksController index

This will generate a controller called BooksController with an index action method.

This will also create an additional route which looks like get books/index. We don’t need that because we’ve already written the route so the generated route can be deleted.

The generated controller can be found under app/controller/books_controller.rb and looks like this:

class BooksController < ApplicationController
  def index
  end
end

As you can see, BooksController is a regular Ruby class that inherits from ApplicationController. The inheritance provides the class with methods for handling incoming requests, params, etc.

You’ll notice that the class was also generated with an empty index method (Rails developers call this an ‘index action’). Even though the method is empty it does have a purpose. Any requests which hit BooksController#index will be served a successful response, with a 204 status code.

Calling the controller action via cURL

We can test that via cURL:

$ curl http://localhost:3000/books -v

You should see that the cURL request returns a 204 status code. We can also look at the server logs:

Started GET "/books" for ::1 at 2020-10-27 19:31:35 +0100
Processed by BooksController#index as */*
Completed 204 No Content in 0ms (ActiveRecord: 0.0ms | Allocations: 32)

The server log shows that we made a GET request to /books, the request was processed by the BooksController#index method and it returned a 204.

Updating the controller action to return a list of objects

Currently BooksController#index returns a successful response code but it doesn’t return any data. Let’s update the method to return a list of book objects:

class BooksController < ApplicationController
  def index
    render json: Book.all
  end
end

We’ll use render, with the json option and pass in an ActiveRecord collection. In this case we use Book.all which will return all books in the database. We haven’t defined the Book model yet but we’ll do that next.

Generating a model

We can generate a model using the Rails generate command. We just need to provide a name for our model and a list of attributes:

rails g model Book title:string author:string

In this example we’re generating a model called Book which has two fields, title and author, both of which are string fields. When we run the command Rails will generate a couple of files for us:

• a migration file - db/migrate/20200620150063_create_books.rb
• a model file - app/models/book.rb
• some test files

Here’s a look inside the files that were created:

book.rb

class Book < ApplicationRecord
end

As you can see there’s not much going on in this file, at the moment. We’re defining a Book class and inheriting from ApplicationRecord. Although we haven’t added any of our own logic, to this file, it still gives us a lot of capabilities. By inheriting from ApplicationRecord we’re giving Book all the power of Rails, by making it an ActiveRecord class.

Rails will map this Ruby class to the book table in our database. We can then use this model to access the database in our Rails application by calling methods. For example: Book.all will return all records.

migration file

class CreateBooks < ActiveRecord::Migration[6.0]
  def change
    create_table :books do |t|
      t.string :title
      t.string :author

      t.timestamps
    end
  end
end

As well as the books model, we need to actually create a database table. To do that, Rails has generated a migration file for us which is like a blueprint for creating a database table. Here we’re creating a table called books with two fields: title and author, both of which are string fields. The table also includes created_at and updated_at timestamps. This table will be used to store books in our system.

If we try to run the server now it will fail because we have migrations in our codebase that haven’t been applied yet. So before we continue we should run the migrations. To do that, we can execute:

$ bin/rails db:migrate

This will apply the migration, creating the books table. You may be wondering which database Rails has updated. Rails ships with sqlite3 by default. When you run the migrations you may notice a new file appear called development.sqlite3. This is your development database.

Testing the controller with cURL

Now that we’ve run the migrations we can test the controller/action again using the cURL request we ran before:

$ curl http://localhost:3000/books
[]

In the response you’ll notice we’re getting back an empty array. This is what we would expect because the controller is returning all books but we don’t have any books in the database to return. This is good because it means the response is consistent whether we have zero, one or multiple books being returned

Creating some database records in the rails console

To test the controller/action when we have records in the database, we can use the rails console. To start the console run:

bin/rails c

Then in the prompt you can create a Book by doing:

> Book.create!(author: 'J.K Rowling', title: 'Harry Potter and the Philosophers Stone')
=> #<Book id: 1, title: "Harry Potter and the Philosophers Stone", author: "J.K Rowling", created_at: "2020-11-20 07:48:12", updated_at: "2020-11-20 07:48:12">

create is an ActiveRecord query method that allows us to create database records. It’s available to all of our ActiveRecord models and takes a hash of database fields as it’s arguments.

Now we can run the cURL request again to see some data in the response body:

$ curl http://localhost:3000/books
[{"id": 1, "title": "Harry Potter and the Philosophers Stone", "author": "J.K Rowling", "created_at": "2020-11-20 07:48:12", "updated_at": "2020-11-20 07:48:12"}]

1. Creating a Rails API Project and Routing
2. Basic Controller and Models
3. Building a POST Endpoint
4. HTTP Status Codes
5. Active Record Validations
6. Destroy Controller Action
7. Exception Handling in Controllers

My background

I’m a software engineer with 10 years industry experience and I’ve been building Ruby on Rails applications for much of that time. A lot of my time with Rails has been spent working on backend APIs. In this tutorial I want to share that knowledge.

The application

In this tutorial series we’re going to build an API backend for a book store. The API should allow us to do things like list the books we have in store, add new books to the store and delete books from our store’s database.

Installing Rails

This tutorial assumes you have Ruby and Rails 6 installed on your machine. If you haven’t done so already GoRails has a good guide on how to do that.

Creating a new Rails API app

To build the application we’re going to be using Rails API-only. This allows us to generate a specialised Rails application that has all the functionality required for building APIs. For a full list of what Rails API-only applications include, you can read the docs. At a high level, Rails API-only does not include the view rendering logic but does include controllers, models, routing, etc.

Let’s create a new Rails API-only application. I’m naming my application “nile” but you can call it whatever you want. To create the application run the following command in the terminal:

$ rails new nile --api

The output should look something like this:

      create
      create  README.md
      create  Rakefile
      create  .ruby-version
      create  config.ru
      create  .gitignore
      create  Gemfile
         run  git init from "."
Initialized empty Git repository in /Users/tomkadwill/workspace/nile/.git/
      create  app
      create  app/assets/config/manifest.js
      create  app/assets/stylesheets/application.css
      create  app/channels/application_cable/channel.rb
      create  app/channels/application_cable/connection.rb
      create  app/controllers/application_controller.rb
      create  app/helpers/application_helper.rb
      .
      .
      .

Rails has created all of the project files for us and installed the default gems.

Now we can cd into the project and open it in our editor (I’m using VSCode but you can use any good text editor):

$ cd nile
$ code .

Adding the first API route

Now that we have initialized the Rails project we can start working on the first API endpoint. To start with, we’re going to be adding an endpoint to return all of the books we have in our store. The route should look like: localhost:3000/books. To do that we can add the following to config/routes.rb:

Rails.application.routes.draw do
  # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
  get '/books' => 'books#index'
end

To see what this has done, we can run rake routes via the command line:

$ bin/rails routes

If you scroll to the top of the console output, you should see the new route:

Prefix Verb   URI Pattern           Controller#Action
books  GET    /books(.:format)      books#index

Our route is correct but we can re-write it in a nicer way:

Rails.application.routes.draw do
  # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
  resources :books
end

The resources method will generate all 7 restful resources. If we run rake routes again we see:

Prefix Verb   URI Pattern           Controller#Action
books  GET    /books(.:format)      books#index
       POST   /books(.:format)      books#create
book   GET    /books/:id(.:format)  books#show
       PATCH  /books/:id(.:format)  books#update
       PUT    /books/:id(.:format)  books#update
       DELETE /books/:id(.:format)  books#destroy

This is great because Rails is able to generate all the routes we need via a single method call. However, we don’t need all of these routes so we can pair it down to just the one we need:

Rails.application.routes.draw do
  # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
  resources :books, only: :index
end

Which will give us:

Prefix Verb   URI Pattern           Controller#Action
books  GET    /books(.:format)      books#index

Starting the development server

Let’s test our new route. To do that we need to start the development server. Rails has a built in command for that:

$ bin/rails server

By default, the rails server will run on http://localhost:3000. If you browse to that url you will see the Rails welcome page.

Hitting our new route

However, this is an API application so we wont be interacting with it via the browser. Instead we can use cURL to make API requests. To make a GET request we can do:

$ curl http://localhost:3000/books

You should get an error ActionController::RoutingError uninitialized constant BooksController. That’s because the route we set up assumes there is a controller called BooksController and tries to route to straight to it. Don’t worry, in part 2 we’ll add the controller and have the whole API request/response working.

This slows me down because I use the source control sidebar for navigation. I like to jump to edited files and tidy them up before committing to GitHub.

You can disable this feature by searching for openDiffOnClick in settings and un-checking it:

With openDiffOnClick disabled you’ll jump straight to files for editing. Just like you would when navigating via the file explorer.