api_navigator 0.0.1

data/spec/fixtures/sample.json

@@ -0,0 +1,108 @@
+# root
+
+data: {},
+links: {},
+meta: {},
+errors*: []
+
+
+# singular
+
+data: {
+  atr1:
+  atr2:
+  nested: {
+
+  }
+},
+links: {
+  self: "self-url"
+}
+
+
+# multiple
+
+data: [
+
+]
+},
+links: {
+  self: "self-url"
+}
+
+# http://localhost:3000/sample/book/1?include=[publisher,authors]&render=compact
+data: {
+  title: 'Book 1',
+  body: 'Book 1 Body',
+  year: 1999,
+  publisher: {
+    data: {
+      name: 'Manning Publisher',
+    },
+    _links: {
+      self: {
+        href: "http://localhost:3000/sample/publisher/1",
+      }
+    },
+    _meta: { type: "book" }                              
+  },
+  authors: {
+    data: [
+      # author1,
+      # author2
+    ],
+    _links: {},
+    _meta: {}
+  }
+},
+_links: {
+  self: {
+    href: "http://localhost:3000/sample/books/1",
+  },
+  authors: {
+    href: "http://localhost:3000/sample/book/1/authors",
+  },
+  publisher: {
+    href: "http://localhost:3000/sample/book/1/publisher",
+  },
+},
+_meta: { type: "book" }                              
+
+
+data: {
+  title: 'Book 1',
+  body: 'Book 1 Body',
+  year: 1999,
+  _relations: {
+    publisher: {
+      data: {
+        name: 'Manning Publisher',
+      },
+      _links: {
+        self: {
+          href: "http://localhost:3000/sample/publisher/1",
+        }
+      },
+      _meta: { type: "book" }                              
+    },
+    authors: {
+      data: [
+        # author1,
+        # author2
+      ],
+      _links: {},
+      _meta: {}
+    }
+},
+_links: {
+  self: {
+    href: "http://localhost:3000/sample/books/1",
+  },
+  authors: {
+    href: "http://localhost:3000/sample/book/1/authors",
+  },
+  publisher: {
+    href: "http://localhost:3000/sample/book/1/publisher",
+  },
+},
+_meta: { type: "book" }                              

data/spec/lib/api_navigator/attribute_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+module ApiNavigator
+  describe Attributes do
+    let(:representation) do
+      JSON.parse(Fixtures::Requests.book_response)
+    end
+
+    let(:attributes) do
+      Attributes.new(representation.fetch('data'))
+    end
+
+    it 'does not set _links as an attribute' do
+      expect(attributes).not_to respond_to :_links
+    end
+
+    it 'does not set _meta as an attribute' do
+      expect(attributes).not_to respond_to :_meta
+    end
+
+    it 'sets normal attributes' do
+      expect(attributes).to respond_to :title
+      expect(attributes.title).to be == "Book 1"
+
+      expect(attributes).to respond_to :body
+      expect(attributes.body).to be == 'Book 1 Body'
+
+      expect(attributes).to respond_to :year
+      expect(attributes.year).to be == 1999
+    end
+
+    it 'is a collection' do
+      expect(Attributes.ancestors).to include(CollectionHash)
+    end
+  end
+end

data/spec/lib/api_navigator/collection_hash_spec.rb

@@ -0,0 +1,71 @@
+require 'spec_helper'
+
+module ApiNavigator
+  describe CollectionHash do
+    let(:representation) do
+      JSON.parse(Fixtures::Requests.book_response)
+    end
+
+    let(:collection) do
+      CollectionHash.new(representation)
+    end
+
+    it 'exposes the collection as methods' do
+      expect(collection.data['title']).to be == 'Book 1'
+      expect(collection.data).to be_kind_of Hash
+    end
+
+    it 'exposes collection as a hash' do
+      expect(collection['data']['body']).to be == 'Book 1 Body'
+      expect(collection['data']).to be_kind_of Hash
+    end
+
+    it 'correctly responds to methods' do
+      expect(collection).to respond_to :data
+    end
+
+    it 'acts as enumerable' do
+      names = collection.map do |name, _value|
+        name
+      end
+      expect(names).to include(*%w[data _links _meta])
+    end
+
+    describe '#to_hash' do
+      it 'returns the wrapped collection as a hash' do
+        expect(collection.to_hash).to be_kind_of Hash
+      end
+    end
+
+    describe 'include?' do
+      it 'returns true for keys that exist' do
+        expect(collection.include?('_links')).to be_truthy
+      end
+
+      it 'returns false for missing keys' do
+        expect(collection.include?('missing key')).to be_falsey
+      end
+    end
+
+    describe '#fetch' do
+      it 'returns the value for keys that exist' do
+        expect(collection.fetch('data')).to be == representation['data']
+        expect(collection.fetch('data').fetch('title')).to be == 'Book 1'
+      end
+
+      it 'raises an error for missing keys' do
+        expect { collection.fetch('missing key') }.to raise_error KeyError
+      end
+
+      describe 'with a default value' do
+        it 'returns the value for keys that exist' do
+          expect(collection.fetch('data', 'a_string')).to be_kind_of Hash
+        end
+
+        it 'returns the default value for missing keys' do
+          expect(collection.fetch('missing key', 'default')).to be == 'default'
+        end
+      end
+    end
+  end
+end

data/spec/lib/api_navigator/entry_point_spec.rb

@@ -0,0 +1,185 @@
+require 'spec_helper'
+
+module ApiNavigator
+  describe EntryPoint do
+    describe 'default' do
+      let(:entry_point) do
+        EntryPoint.new 'http://my.api.org'
+      end
+
+      describe 'connection' do
+        it 'creates a Faraday connection with the entry point url' do
+          expect(entry_point.connection.url_prefix.to_s).to be == 'http://my.api.org/'
+        end
+
+        it 'creates a Faraday connection with the default headers' do
+          expect(entry_point.headers['Content-Type']).to be == 'application/hal+json'
+          expect(entry_point.headers['Accept']).to be == 'application/hal+json,application/json'
+        end
+
+        it 'can update headers after a connection has been constructed' do
+          expect(entry_point.connection).to be_kind_of(Faraday::Connection)
+          entry_point.headers.update('Content-Type' => 'application/foobar')
+          expect(entry_point.headers['Content-Type']).to be == 'application/foobar'
+        end
+
+        it 'can insert additional middleware after a connection has been constructed' do
+          expect(entry_point.connection).to be_kind_of(Faraday::Connection)
+          entry_point.connection.use :instrumentation
+          handlers = entry_point.connection.builder.handlers
+          expect(handlers).to include FaradayMiddleware::Instrumentation
+        end
+
+        it 'creates a Faraday connection with the default block' do
+          handlers = entry_point.connection.builder.handlers
+
+          expect(handlers).to include Faraday::Response::RaiseError
+          expect(handlers).to include FaradayMiddleware::FollowRedirects
+          expect(handlers).to include FaradayMiddleware::EncodeHalJson
+          expect(handlers).to include FaradayMiddleware::ParseHalJson
+          expect(handlers).to include Faraday::Adapter::NetHttp
+
+          expect(entry_point.connection.options.params_encoder).to be == Faraday::FlatParamsEncoder
+        end
+
+        it 'raises a  ConnectionAlreadyInitializedError if attempting to modify headers' do
+          expect(entry_point.connection).to be_kind_of Faraday::Connection
+          expect{ entry_point.headers = {} }.to raise_error ConnectionAlreadyInitializedError
+        end
+
+        it 'raises a  ConnectionAlreadyInitializedError if attempting to modify the faraday block' do
+          expect(entry_point.connection).to be_kind_of Faraday::Connection
+          expect{ entry_point.connection {} }.to raise_error ConnectionAlreadyInitializedError
+        end
+      end
+
+      describe 'initialize' do
+        it 'sets a Link with the entry point url' do
+          expect(entry_point._url).to be == 'http://my.api.org'
+        end
+      end
+    end
+
+    describe 'faraday_options' do
+      let(:entry_point) do
+        EntryPoint.new 'http://my.api.org' do |entry_point|
+          entry_point.faraday_options = { proxy: 'http://my.proxy:8080' }
+        end
+      end
+
+      describe 'connection' do
+        it 'creates a Faraday connection with the entry point url' do
+          expect(entry_point.connection.url_prefix.to_s).to be == 'http://my.api.org/'
+        end
+
+        it 'creates a Faraday connection with the default headers' do
+          expect(entry_point.headers['Content-Type']).to be == 'application/hal+json'
+          expect(entry_point.headers['Accept']).to be == 'application/hal+json,application/json'
+        end
+
+        it 'creates a Faraday connection with options' do
+          expect(entry_point.connection.proxy).to be_kind_of Faraday::ProxyOptions
+          expect(entry_point.connection.proxy.uri.to_s).to be == 'http://my.proxy:8080'
+        end
+      end
+    end
+
+    describe 'options' do
+      let(:entry_point) do
+        EntryPoint.new 'http://my.api.org' do |entry_point|
+          entry_point.connection(proxy: 'http://my.proxy:8080')
+        end
+      end
+
+      describe 'connection' do
+        it 'creates a Faraday connection with the entry point url' do
+          expect(entry_point.connection.url_prefix.to_s).to be == 'http://my.api.org/'
+        end
+
+        it 'creates a Faraday connection with the default headers' do
+          expect(entry_point.headers['Content-Type']).to be == 'application/hal+json'
+          expect(entry_point.headers['Accept']).to be == 'application/hal+json,application/json'
+        end
+
+        it 'creates a Faraday connection with options' do
+          expect(entry_point.connection.proxy).to be_kind_of Faraday::ProxyOptions
+          expect(entry_point.connection.proxy.uri.to_s).to be == 'http://my.proxy:8080'
+        end
+      end
+    end
+
+    describe 'custom' do
+      let(:entry_point) do
+        EntryPoint.new 'http://my.api.org' do |entry_point|
+          entry_point.connection(default: false) do |conn|
+            conn.request :json
+            conn.response :json, content_type: /\bjson$/
+            conn.adapter :net_http
+          end
+
+          entry_point.headers = {
+            'Content-Type' => 'application/foobar',
+            'Accept' => 'application/foobar'
+          }
+        end
+      end
+
+      describe 'connection' do
+        it 'creates a Faraday connection with the entry point url' do
+          expect(entry_point.connection.url_prefix.to_s).to be == 'http://my.api.org/'
+        end
+
+        it 'creates a Faraday connection with non-default headers' do
+          expect(entry_point.headers['Content-Type']).to be == 'application/foobar'
+          expect(entry_point.headers['Accept']).to be == 'application/foobar'
+        end
+
+        it 'creates a Faraday connection with the default block' do
+          handlers = entry_point.connection.builder.handlers
+          # TODO - we are below not included?
+          # expect(handlers).to include Faraday::Response::RaiseError
+          # expect(handlers).to include FaradayMiddleware::FollowRedirects
+          expect(handlers).to include FaradayMiddleware::EncodeJson
+          expect(handlers).to include FaradayMiddleware::ParseJson
+          expect(handlers).to include Faraday::Adapter::NetHttp
+        end
+      end
+    end
+
+    describe 'inherited' do
+      let(:entry_point) do
+        EntryPoint.new 'http://my.api.org' do |entry_point|
+          entry_point.connection do |conn|
+            conn.use Faraday::Request::OAuth
+          end
+          entry_point.headers['Access-Token'] = 'token'
+        end
+      end
+
+      describe 'connection' do
+        it 'creates a Faraday connection with the default and additional headers' do
+          expect(entry_point.headers['Content-Type']).to be == 'application/hal+json'
+          expect(entry_point.headers['Accept']).to be == 'application/hal+json,application/json'
+          expect(entry_point.headers['Access-Token']).to be == 'token'
+        end
+
+        it 'creates a Faraday connection with the entry point url' do
+          expect(entry_point.connection.url_prefix.to_s).to be == 'http://my.api.org/'
+        end
+
+        it 'creates a Faraday connection with the default block plus any additional handlers' do
+          handlers = entry_point.connection.builder.handlers
+
+          expect(handlers).to include Faraday::Request::OAuth
+          expect(handlers).to include Faraday::Response::RaiseError
+          expect(handlers).to include FaradayMiddleware::FollowRedirects
+          expect(handlers).to include FaradayMiddleware::EncodeHalJson
+          expect(handlers).to include FaradayMiddleware::ParseHalJson
+          expect(handlers).to include Faraday::Adapter::NetHttp
+
+          expect(entry_point.connection.options.params_encoder).to be == Faraday::FlatParamsEncoder
+        end
+      end
+    end
+  end
+end

data/spec/lib/api_navigator/link_collection_spec.rb

@@ -0,0 +1,77 @@
+require 'spec_helper'
+
+module ApiNavigator
+  describe LinkCollection do
+    let(:entry_point) { double('EntryPoint', config: { base_uri: '/' }) }
+
+    let(:representation) do
+      JSON.parse(Fixtures::Requests.root_response)
+    end
+
+    let(:links) do
+      LinkCollection.new(representation['_links'], representation['_links']['curies'], entry_point)
+    end
+
+    it 'is a CollectionHash' do
+      expect(LinkCollection.ancestors).to include CollectionHash
+    end
+
+    it 'initializes the collection with links' do
+      expect(links).to respond_to(:books)
+    end
+
+    it 'returns link objects for each link' do
+      expect(links.books).to be_kind_of Link
+      expect(links['self']).to be_kind_of Link
+
+      expect(links.two_links).to be_kind_of Array
+      expect(links['two_links']).to be_kind_of Array
+    end
+
+    describe 'plain link' do
+      let(:plain_link) { links.books }
+      it 'must be correct' do
+        expect(plain_link._url).to be == '/books'
+      end
+    end
+
+    describe 'templated link' do
+      let(:templated_link) { links.filter }
+      it 'must expand' do
+        expect(templated_link._expand(filter: 'gizmos')._url).to be == '/productions/1?categories=gizmos'
+      end
+    end
+
+    describe 'curied link collection' do
+      let(:curied_link) { links['api:authors'] }
+      let(:curie) { links._curies['api'] }
+      it 'must expand' do
+        expect(curied_link._expand(rel: 'assoc')._url).to be == '/api/authors'
+      end
+      it 'exposes curie' do
+        expect(curie.expand('authors')).to be == '/docs/resources/authors'
+      end
+    end
+
+    describe 'array of links' do
+      let(:two_links) { links.two_links }
+
+      it 'should have 2 items' do
+        expect(two_links.length).to be == 2
+      end
+
+      it 'must be an array of Links' do
+        two_links.each do |link|
+          expect(link).to be_kind_of Link
+        end
+      end
+    end
+
+    describe 'null link value' do
+      let(:null_link) { links.null_link }
+      it 'must be nil' do
+        expect(null_link).to be_nil
+      end
+    end
+  end
+end