wp-api-client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d1e0339d85de70f76fa1053b11e8c81d34498b57
-  data.tar.gz: 96321f28e3713c144ee3d580e364ead14a530268
+  metadata.gz: a7a1b56612823b783b538e87dc5caf6ed4e00781
+  data.tar.gz: 103661f8e6887d36dd16d2c09f0f20f89958928e
 SHA512:
-  metadata.gz: 0852242e985bd4de60df6820b522845f422f608e1db5efe3e0e40f429ec5353bbdd6310d0050d9a18edb7aef05c91a6ec2d127b76b29d4db2d751a48bed59bff
-  data.tar.gz: f7bc70aa9662df06d7916f647119021113ff04c838ccb0090681618436b2cbf341d850425f18851b5839eea9108cf9e0638c759fb5a60aaec462c004a6cff3fc
+  metadata.gz: b714dee47f9db903f43ae53d755164e8c92f791a2c531e99ad52c72c016765f304575b46b07e42629bbc0fb699f786114b6c207626c87098f467fc80fbf01ee4
+  data.tar.gz: bbe61828ae974866f0ece28763ce654a2d34fdaf1b3b2c18b20ea552815d8e2dcb13dce8f7fae7ecc121c5a854f1516515e1165f088614a81e33578c8a2c7680

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/config/oauth.json

data/Gemfile

@@ -0,0 +1,3 @@
+# A sample Gemfile
+source "https://rubygems.org"
+gemspec

data/README.md

@@ -2,9 +2,9 @@
 
 This unambitious client provides read-only access for WP-API v2.
 
-It does not support authentication (yet).
+It supports authentication via OAuth.
 
-It does not support comments or POST requests.
+It does not support comments, users or POST requests.
 
 It requires **Ruby 2.3** and is tested against **WP-API 2.0-beta12**.
 
@@ -26,8 +26,12 @@ require 'wp_api_client'
 
 ```ruby
 # create a client
-@connection = WpApiClient::Connection.new('http://localhost:8080/wp-json/wp/v2')
-@api = WpApiClient::Client.new(@connection)
+
+WpApiClient.configure do |api_client|
+  api_client.endpoint = 'http://example.com/wp-json/wp/v2'
+end
+
+@api = WpApiClient.get_client
 
 # get some posts
 posts = @api.get('custom_post_type/') # or "posts/" etc
@@ -51,7 +55,7 @@ term.taxonomy
 term.posts
 # => #<WpApiClient::Collection:0x007fd65d07d588 @resources=[#<WpApiClient::Entities::Post...
 
-# term.posts.first.terms.first.taxonomy.terms.first... etc etc etc
+# term.posts("custom_post_type").first.terms("category").first.taxonomy... etc etc etc
 ```
 
 #### Pagination
@@ -72,6 +76,54 @@ page_after_that = @api.get(next_page.page_after_that)
 # => #<WpApiClient::Collection:0x00bbcafe938827 @resources=[#<WpApiClient::Entities::Post...
 ```
 
+#### Defining relationships
+
+The [REST API docs](http://v2.wp-api.org/extending/linking/) invite you to define
+custom relationships to go alongside "http://api.w.org/term" etc.
+
+For example, let's say you have a `person` post type and a post-to-post relation
+defined through meta and exposed in the REST API like this:
+
+```php
+add_filter( 'rest_prepare_king', function( $data, $king ) {
+	if( $king->queen ) {
+		$data->add_link(
+			'http://api.myuniqueuri.com/marriage',
+			rest_url( '/wp/v2/person/'.$king->queen ),
+			['embeddable' => true]
+		);
+	}
+	return $data;
+}, 10, 2);
+```
+
+This will cause the `http://api.myuniqueuri.com/marriage` relation to be reflected
+in your `_links` property when you call up the King from the REST API.
+
+But you'll get an error if you try to query this relationship using the client.
+
+```ruby
+king = @api.get('person/1')
+queen = king.relations("http://api.myuniqueuri.com/marriage").first
+# => throws WpApiClient::RelationNotDefined
+```
+
+The solution is to register the relationship on configuration:
+
+```ruby
+WpApiClient.configure do |c|
+  c.define_mapping("http://api.myuniqueuri.com/marriage", :post)
+end
+
+...
+
+king = @api.get('person/1')
+queen = king.relations("http://api.myuniqueuri.com/marriage").first
+# => #<WpApiClient::Entities::Post:0x007fed42b3e458 @resource={"id"=>2...
+```
+
+There is currently support for `:post_type`, `:post`, `:term` and `:meta` (key/value) relations.
+
 #### Loading a taxonomy via a slug
 
 WP-API returns an array even if there's only one result, so you need to be careful here
@@ -82,11 +134,25 @@ taxonomy_name = term.taxonomy.name
 posts = term.posts
 ```
 
+#### OAuth
+
+Provide a symbol-keyed hash of `token`, `token_secret`, `consumer_key` and `consumer_secret` on configuration.
+
+```ruby
+WpApiClient.configure do |api_client|
+  api_client.oauth_credentials = oauth_credentials_hash
+end
+
+client = WpApiClient.get_client
+```
+
 ## Testing and compatibility
 
 This library comes with VCR cassettes recorded against a local WP installation
 running WP-API v2-beta12. It is not tested with other versions.
 
+If you want to make your own VCR cassettes, use [these scripts](https://github.com/duncanjbrown/WP-REST-Test).
+
 To run the tests, invoke `rspec`.
 
 ## Structure
@@ -119,12 +185,10 @@ next_page = @api.get(posts.next_page)
 # => #<WpApiClient::Collection:0x00bbcafe938827 @resources=[#<WpApiClient::Entities::Post...
 ```
 
-#### `WpApiClient::Entities::BaseEntity`
+#### `WpApiClient::Entities::Base`
 
-Base class for `Post`, `Term` and `Taxonomy`, so far. Not all methods are implemented.
+Base class for `Post`, `Term`, `Image` and `Taxonomy`, so far. Not all methods are implemented.
 
 ## Other
 
-This library puts `?_embed` on every request to save on HTTP requests right now.
-
 Thanks [WP-API](https://github.com/WP-API/WP-API)!

data/lib/wp_api_client.rb

@@ -1,10 +1,29 @@
 require "wp_api_client/version"
+require "wp_api_client/configuration"
+
+require "wp_api_client/entities/base"
 
-require "wp_api_client/entities/base_entity"
 require "wp_api_client/entities/post"
+require "wp_api_client/entities/meta"
 require "wp_api_client/entities/taxonomy"
 require "wp_api_client/entities/term"
+require "wp_api_client/entities/image"
+require "wp_api_client/entities/types"
 
 require "wp_api_client/client"
 require "wp_api_client/connection"
 require "wp_api_client/collection"
+require "wp_api_client/relationship"
+
+module WpApiClient
+  def self.get_client
+    @client ||= Client.new(Connection.new(configuration))
+  end
+
+  # for tests
+  def self.reset!
+    @client = nil
+  end
+
+  class RelationNotDefined < StandardError; end
+end

data/lib/wp_api_client/client.rb

@@ -1,12 +1,6 @@
 module WpApiClient
   class Client
 
-    Types = [
-      WpApiClient::Entities::Post,
-      WpApiClient::Entities::Term,
-      WpApiClient::Entities::Taxonomy
-    ]
-
     def initialize(connection)
       @connection = connection
     end
@@ -26,21 +20,11 @@ module WpApiClient
 
     # Take the API response and figure out what it is
     def native_representation_of(response_body)
+      # Do we have a collection of objects?
       if response_body.is_a? Array
-        collection = true
-        object = response_body.first
-      else
-        collection = false
-        object = response_body
-      end
-
-      type = Types.find { |type| type.represents?(object) }
-
-      if collection
-        resources = response_body.map! { |object| type.new(object, self) }
-        WpApiClient::Collection.new(resources, @headers)
+        WpApiClient::Collection.new(response_body, @headers)
       else
-        type.new(response_body, self)
+        WpApiClient::Entities::Base.build(response_body)
       end
     end
   end

data/lib/wp_api_client/collection.rb

@@ -4,10 +4,13 @@ module WpApiClient
 
     attr_accessor :resources, :total_available
 
-    def initialize(resources, headers)
-      @resources = resources
-      @links = parse_link_header(headers['Link'])
-      @total_available = headers['X-WP-TOTAL'].to_i
+    def initialize(resources, headers = nil)
+      resources = [resources] unless resources.is_a? Array
+      @resources = resources.map { |object| WpApiClient::Entities::Base.build(object) }
+      if headers
+        @links = parse_link_header(headers['Link'])
+        @total_available = headers['X-WP-TOTAL'].to_i
+      end
     end
 
     def each(&block)
@@ -22,10 +25,6 @@ module WpApiClient
       @links[:prev] && @links[:prev]
     end
 
-    def method_missing(sym)
-      @resources.send(sym)
-    end
-
 private
 
     # https://www.snip2code.com/Snippet/71914/Parse-link-headers-from-Github-API-in-Ru

data/lib/wp_api_client/configuration.rb

@@ -0,0 +1,44 @@
+module WpApiClient
+
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset
+    @configuration = Configuration.new
+  end
+
+  class Configuration
+    attr_accessor :endpoint
+    attr_accessor :embed
+    attr_accessor :oauth_credentials
+    attr_accessor :debug
+    attr_accessor :cache
+
+    def initialize
+      @endpoint = 'http://localhost:8080/wp-json/wp/v2'
+      @embed = true
+    end
+
+    def define_mapping(relation, type)
+      WpApiClient::Relationship.define(relation, type)
+    end
+
+    def request_params
+      params = {}
+      if @embed
+        params[:_embed] = true
+      end
+      params
+    end
+
+  end
+end

data/lib/wp_api_client/connection.rb

@@ -1,15 +1,29 @@
 require 'faraday'
 require 'faraday_middleware'
+require 'faraday-http-cache'
 
 module WpApiClient
   class Connection
 
     attr_accessor :headers
 
-    def initialize(endpoint)
-      @conn = Faraday.new(:url => endpoint) do |faraday|
-        faraday.request  :url_encoded             # form-encode POST params
-        #faraday.response :logger                  # log requests to STDOUT
+    def initialize(configuration)
+      @configuration = configuration
+      @conn = Faraday.new(url: configuration.endpoint) do |faraday|
+
+        if configuration.oauth_credentials
+          faraday.use FaradayMiddleware::OAuth, configuration.oauth_credentials
+        end
+
+        if configuration.debug
+          faraday.response :logger
+        end
+
+        if configuration.cache
+          faraday.use :http_cache, store: configuration.cache
+        end
+
+        faraday.use Faraday::Response::RaiseError
         faraday.response :json, :content_type => /\bjson$/
         faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
       end
@@ -17,7 +31,7 @@ module WpApiClient
 
     # translate requests into wp-api urls
     def get(url, params = {})
-      @conn.get url, params.merge({_embed: true})
+      @conn.get url, params.merge(@configuration.request_params)
     end
   end
 end

data/lib/wp_api_client/entities/base.rb

@@ -0,0 +1,36 @@
+require 'open-uri'
+
+module WpApiClient
+  module Entities
+    class Base
+      attr_reader :resource
+
+      def self.build(resource)
+        raise Exception if resource.nil?
+        type = WpApiClient::Entities::Types.find { |type| type.represents?(resource) }
+        type.new(resource)
+      end
+
+      def initialize(resource)
+        unless resource.is_a? Hash
+          raise ArgumentError.new('Tried to initialize a WP-API resource with something other than a Hash')
+        end
+        @resource = resource
+      end
+
+      def links
+        resource["_links"]
+      end
+
+      def relations(relation, relation_to_return = nil)
+        relationship = Relationship.new(@resource, relation)
+        relations = relationship.get_relations
+        if relation_to_return
+          relations[relation_to_return]
+        else
+          relations
+        end
+      end
+    end
+  end
+end

data/lib/wp_api_client/entities/image.rb

@@ -0,0 +1,15 @@
+module WpApiClient
+  module Entities
+    class Image < Base
+      alias :image :resource
+
+      def self.represents?(json)
+        json["media_type"] and json["media_type"] == 'image'
+      end
+
+      def sizes(size = :full)
+        image.dig("media_details", "sizes", size.to_s, "source_url")
+      end
+    end
+  end
+end

data/lib/wp_api_client/entities/meta.rb

@@ -0,0 +1,19 @@
+module WpApiClient
+  module Entities
+    class Meta < Base
+      alias :meta :resource
+
+      def self.represents?(json)
+        json["key"] and json["value"]
+      end
+
+      def key
+        meta["key"]
+      end
+
+      def value
+        meta["value"]
+      end
+    end
+  end
+end

data/lib/wp_api_client/entities/post.rb

@@ -1,6 +1,6 @@
 module WpApiClient
   module Entities
-    class Post < BaseEntity
+    class Post < Base
       alias :post :resource
 
       def self.represents?(json)
@@ -11,28 +11,32 @@ module WpApiClient
         post["title"]["rendered"]
       end
 
+      def slug
+        post["slug"]
+      end
+
       def date
-        Time.new(post["date_gmt"])
+        Time.parse(post["date_gmt"]) if post["date_gmt"]
       end
 
       def content
         post["content"]["rendered"]
       end
 
+      def excerpt
+        post["excerpt"]["rendered"]
+      end
+
       def id
         post["id"]
       end
 
-      def terms
-        if embedded?
-          terms = []
-          embedded["https://api.w.org/term"].map do |taxonomy|
-            taxonomy.each do |term|
-              terms << WpApiClient::Entities::Term.new(term, @api)
-            end
-          end
-          terms
-        end
+      def terms(taxonomy = nil)
+        relations("https://api.w.org/term", taxonomy)
+      end
+
+      def meta(key = nil)
+        @meta ||= relations("https://api.w.org/meta", key)
       end
     end
   end

data/lib/wp_api_client/entities/taxonomy.rb

@@ -1,6 +1,6 @@
 module WpApiClient
   module Entities
-    class Taxonomy < BaseEntity
+    class Taxonomy < Base
       alias :taxonomy :resource
 
       def self.represents?(json)
@@ -12,7 +12,7 @@ module WpApiClient
       end
 
       def terms
-        @api.get(links["https://api.w.org/items"].first["href"])
+        relations("https://api.w.org/items")
       end
     end
   end

data/lib/wp_api_client/entities/term.rb

@@ -1,6 +1,6 @@
 module WpApiClient
   module Entities
-    class Term < BaseEntity
+    class Term < Base
       alias :term :resource
 
       def self.represents?(json)
@@ -8,13 +8,11 @@ module WpApiClient
       end
 
       def taxonomy
-        @api.get(links["about"].first["href"])
+        WpApiClient.get_client.get(links["about"].first["href"])
       end
 
-      def posts(post_type = "post")
-        post_type_links = links["http://api.w.org/v2/post_type"]
-        link = post_type_links.find { |link| link["href"] =~ /wp\/v2\/#{post_type}/ }
-        @api.get(link["href"]) if link
+      def posts(post_type = nil)
+        relations("http://api.w.org/v2/post_type", post_type)
       end
 
       def name

data/lib/wp_api_client/entities/types.rb

@@ -0,0 +1,11 @@
+module WpApiClient
+  module Entities
+    Types = [
+      Image,
+      Post,
+      Meta,
+      Term,
+      Taxonomy
+    ]
+  end
+end

data/lib/wp_api_client/relationship.rb

@@ -0,0 +1,110 @@
+require 'open-uri'
+
+module WpApiClient
+  class Relationship
+
+    class << self
+      attr_writer :mappings
+
+      def mappings
+        @mappings ||= default_mappings
+      end
+
+      def define(relation, type)
+        mappings[relation] = type
+      end
+
+      def default_mappings
+        {
+          "https://api.w.org/term" => :term,
+          "https://api.w.org/items" => :terms,
+          "http://api.w.org/v2/post_type" => :post_type,
+          "https://api.w.org/meta" => :meta,
+          "https://api.w.org/featuredmedia" => :post
+        }
+      end
+
+      def term(r)
+        relations = {}
+        r.resource["_links"][r.relation].each_with_index do |link, position|
+          relations.merge! Hash[link["taxonomy"], r.load_relation(r.relation, position)]
+        end
+        relations
+      end
+
+      def terms(r)
+        r.load_relation(r.relation, 0)
+      end
+
+      def post_type(r)
+        relations = {}
+        r.resource["_links"][r.relation].each_with_index do |link, position|
+          # get the post type out of the linked URL.
+          post_type = URI.parse(link["href"]).path.split('wp/v2/').pop.split('/').first
+          relations.merge! Hash[post_type, r.load_relation(r.relation, position)]
+        end
+        relations
+      end
+
+      def post(r)
+        r.load_relation(r.relation)
+      end
+
+      def meta(r)
+        relations = {}
+        meta = WpApiClient.get_client.get(r.resource["_links"][r.relation].first["href"])
+        meta.map do |m|
+          relations.merge! Hash[m.key, m.value]
+        end
+        relations
+      end
+    end
+
+    attr_reader :resource
+    attr_reader :relation
+
+    def initialize(resource, relation)
+      @resource = resource
+      @relation = relation
+    end
+
+    def get_relations
+      mapping = self.class.mappings[@relation]
+      if !mapping
+        raise WpApiClient::RelationNotDefined.new %{
+=> The relation "#{@relation}" is not defined.
+
+To add a new relation, define it at configuration. For example, to define this
+relation as one that links to a post object, you would do the following.
+
+WpApiClient.configure do |c|
+  c.define_mapping(#{@relation}, :post)
+end
+
+The currently defined relations are:
+
+#{self.class.mappings.keys.join("\n") }
+
+Available mappings are :post, :term, and :meta.}
+      end
+
+      # Only try to fetch the relation if there are any links to it
+      self.class.send(mapping, self) if resource["_links"][relation]
+    end
+
+    # try to load an embedded object; call out to the API if not
+    def load_relation(relationship, position = nil)
+      if objects = @resource.dig("_embedded", relationship)
+        location = position ? objects[position] : objects
+        WpApiClient::Collection.new(location)
+      else
+        unless position.nil?
+          location = @resource["_links"].dig(relationship, position.to_i, "href")
+        else
+          location = @resource["_links"][relationship]["href"]
+        end
+        WpApiClient.get_client.get(location) if location
+      end
+    end
+  end
+end

data/lib/wp_api_client/version.rb

@@ -1,3 +1,3 @@
 module WpApiClient
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/wp_api_client.gemspec

@@ -30,6 +30,8 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "faraday", "~> 0.9"
   spec.add_dependency "faraday_middleware", "~> 0.10"
+  spec.add_dependency "faraday-http-cache", "~> 1.2"
+  spec.add_dependency "simple_oauth", "~> 0.3"
 
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wp-api-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Duncan Brown
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-01 00:00:00.000000000 Z
+date: 2016-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -38,6 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: faraday-http-cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: simple_oauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -105,6 +133,7 @@ files:
 - ".rspec"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
+- Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -113,11 +142,16 @@ files:
 - lib/wp_api_client.rb
 - lib/wp_api_client/client.rb
 - lib/wp_api_client/collection.rb
+- lib/wp_api_client/configuration.rb
 - lib/wp_api_client/connection.rb
-- lib/wp_api_client/entities/base_entity.rb
+- lib/wp_api_client/entities/base.rb
+- lib/wp_api_client/entities/image.rb
+- lib/wp_api_client/entities/meta.rb
 - lib/wp_api_client/entities/post.rb
 - lib/wp_api_client/entities/taxonomy.rb
 - lib/wp_api_client/entities/term.rb
+- lib/wp_api_client/entities/types.rb
+- lib/wp_api_client/relationship.rb
 - lib/wp_api_client/version.rb
 - wp_api_client.gemspec
 homepage: https://github.com/duncanjbrown/wp-api-client

data/lib/wp_api_client/entities/base_entity.rb

@@ -1,25 +0,0 @@
-module WpApiClient
-  module Entities
-    class BaseEntity
-      attr_reader :resource
-
-      def initialize(resource, api)
-        unless resource.is_a? Hash
-          raise ArgumentError.new('Tried to initialize a WP-API resource with something other than a Hash')
-        end
-        @resource = resource
-        @api = api
-      end
-
-      def links
-        resource["_links"]
-      end
-
-      def embedded
-        resource["_embedded"]
-      end
-
-      alias :embedded? :embedded
-    end
-  end
-end