API proof of concept: forums#show

Gemfile

@@ -7,6 +7,7 @@ gemspec
 gem 'pry-rails'
 gem 'pry-nav'
 gem 'select2-rails', '~> 3.5.4'
+gem 'jbuilder'
 
 platforms :jruby do
   gem "activerecord-jdbc-adapter", :require => false

app/controllers/forem/api/v1/forums_controller.rb

@@ -0,0 +1,13 @@
+require_dependency "forem/application_controller"
+
+module Forem
+  module Api
+    module V1
+      class ForumsController < ApplicationController
+        load_and_authorize_resource :class => 'Forem::Forum', :only => :show
+
+        before_action { request.format = :json }
+      end
+    end
+  end
+end

app/views/forem/api/v1/forums/show.json.jbuilder

@@ -0,0 +1,24 @@
+json.data do
+  json.type "forums"
+  json.(@forum, :id)
+  json.attributes do
+    json.(@forum, :title, :slug)
+  end
+end
+
+json.relationships do
+  json.topics do
+    json.data @forum.topics do |topic|
+      json.type 'topics'
+      json.(topic, :id)
+    end
+  end
+end
+
+json.included @forum.topics do |topic|
+  json.type 'topics'
+  json.(topic, :id)
+  json.attributes do
+    json.(topic, :subject)
+  end
+end

config/routes.rb

@@ -1,3 +1,5 @@
+require 'forem/api/version_routing_constraint'
+
 Forem::Engine.routes.draw do
   root :to => "forums#index"
 
@@ -48,4 +50,12 @@
       end
     end
   end
+
+  namespace :api do
+    constraints Forem::API::VersionRoutingConstraint.new(1) do
+      scope module: :v1 do
+        resources :forums
+      end
+    end
+  end
 end

forem.gemspec

@@ -31,4 +31,5 @@ Gem::Specification.new do |s|
   s.add_dependency 'select2-rails', '~> 3.5.4'
   s.add_dependency 'friendly_id', '~> 5.0.0'
   s.add_dependency 'cancancan', '~> 1.7'
+  s.add_dependency 'jbuilder'
 end

lib/forem/api/version_routing_constraint.rb

@@ -0,0 +1,45 @@
+module Forem
+  module API
+    class VersionRoutingConstraint
+      def initialize(version)
+        @version = version
+      end
+
+      def matches?(request)
+        requested_this_version?(request) ||
+          # All real clients should specify an API version in their
+          # request headers, but for ease of debugging (via curl, browsers,
+          # etc.), the latest API version responds to requests that don't
+          # specify.
+          (no_requested_version?(request) && latest_version?)
+      end
+
+      private
+
+      def requested_this_version?(request)
+        requested_version(request) == @version
+      end
+
+      def no_requested_version?(request)
+        !requested_version(request)
+      end
+
+      def requested_version(request)
+        accept = request.headers['Accept']
+        accept &&
+          accept[/application\/vnd\.forem\+json; version=([0-9]+)/] &&
+          Integer($1)
+      end
+
+      # True if no later API version exists.
+      def latest_version?
+        "::Forem::Api::V#{@version + 1}".constantize
+        # if the above succeeds, this is not the latest version
+        false
+      rescue NameError
+        # no version beyond this one exists
+        true
+      end
+    end
+  end
+end

spec/requests/api/forums_api_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+describe 'Forums API', type: :request do
+  let(:forum) { create(:forum) }
+  let!(:topic) { create(:topic, forum: forum) }
+
+  def api(method, action, params = {})
+    send method, action, params,
+      Accept: 'application/vnd.forem+json; version=1'
+  end
+
+  describe '#show' do
+    before { api :get, api_forum_path(forum) }
+
+    let(:json) { JSON.parse(response.body).with_indifferent_access }
+    let(:data) { json[:data] }
+
+    it 'succeeds' do
+      expect(response).to be_success
+    end
+
+    it 'represents the forum' do
+      expect(data[:type]).to eq 'forums'
+      expect(data[:id]).to eq forum.id
+      expect(data[:attributes][:title]).to eq forum.title
+      expect(data[:attributes][:slug]).to eq forum.slug
+    end
+
+    let(:related_topics) { json[:relationships][:topics] }
+    let(:included_objects) { json[:included] }
+
+    it 'describes topic relationships' do
+      expect(related_topics[:data].length).to eq 1
+      related_topic = related_topics[:data].first
+
+      expect(related_topic[:type]).to eq 'topics'
+      expect(related_topic[:id]).to eq topic.id
+    end
+
+    it 'includes topic data' do
+      expect(included_objects.length).to eq 1
+      included_topic = included_objects.first
+
+      expect(included_topic[:type]).to eq 'topics'
+      expect(included_topic[:id]).to eq topic.id
+      expect(included_topic[:attributes][:subject]).to eq topic.subject
+    end
+  end
+end