A read-only Ruby client for WP-API v2
This unambitious client provides read-only access for WP-API v2.
It supports authentication via OAuth or Basic Auth.
It can make concurrent requests.
It does not support update or create actions. Or comments.
It requires Ruby 2.3 and is tested against the following WordPress versions.
- 4.4
- 4.5 (WP-API 2.0b12)
- 4.5.3 (WP-API 2.0b13)
- 4.7
- 4.7.2
NB If you would like to use 2.0beta13 and up and access post metadata, read the postmeta section in Testing and Compatibility, below.
Installation
gem install wp-api-client
And
require 'wp_api_client'
Usage examples
Set up the client and get some posts
# create a client
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
# => <WpApiClient::Collection:0x007fed432a5660 @resources=[#<WpApiClient::Entities::Post...
posts.map { |p| puts p.title }
# Custom Post Type 99
# Custom Post Type 98
# Custom Post Type 97
term = @posts.first.terms.first
# => #<WpApiClient::Entities::Term:0x007fed42b3e458 @resource={"id"=>2...
post = @api.get("posts/1")
author = post.author
# => #<WpApiClient::Entities::User:0x007fed42b3e458 @resource={"id"=>2...
Navigate between posts, terms and taxonomies
term.taxonomy
# => #<WpApiClient::Entities::Taxonomy:0x007f9c2c86f1a8 @resource={"name"=>"Custom taxonomy"...
term.posts
# => #<WpApiClient::Collection:0x007fd65d07d588 @resources=[#<WpApiClient::Entities::Post...
# term.posts("custom_post_type").first.terms("category").first.taxonomy... etc etc etc
Authors
You can access a given post's author via the author
property.
If you know the ID, you can access a given author's name, avatar etc by querying users/{id}
.
If you would like to access posts grouped by author, you should approach from the
post
end:
@api.get('posts', author: 1)
# => #<WpApiClient::Collection:0x007fd65d07d588 @resources=[#<WpApiClient::Entities::Post...
Pagination
posts = @api.get('posts', page: 2)
posts.count
# => 10
posts.total_available
# => 100
next_page = @api.get(posts.next_page)
# => #<WpApiClient::Collection:0x00bbcafe938827 @resources=[#<WpApiClient::Entities::Post...
page_after_that = @api.get(next_page.next_page)
# => #<WpApiClient::Collection:0x00bbcafe938827 @resources=[#<WpApiClient::Entities::Post...
Relationships
By default the client makes requests with _embed=true
attached. This means that
associated objects that permit embedding will appear in the response. For example, if
you request a post, the post's author will appear in full alongside so you don't
have to make another request to get it.
The client is intelligent enough to figure out whether it can read the content
from an embedded response or if another request is necessary. If you do not want to
request embedded resources by default, you can change embed
to false
when you
configure the client.
Defining relationships
The REST API docs 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:
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.
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:
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
, :user
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
term = @api.get('custom_taxonomy', slug: 'term_one').first
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.
WpApiClient.configure do |api_client|
api_client.oauth_credentials = oauth_credentials_hash
end
client = WpApiClient.get_client
Basic Auth
Provide a symbol-keyed hash of username
and password
on configuration.
WpApiClient.configure do |api_client|
api_client.basic_auth = {username: 'miles', password: 'smile'}
end
client = WpApiClient.get_client
Concurrency
WP-API is slow: a typical request takes 0.5s. To mitigate this, I recommend caching all your responses sensibly, and when you need to fetch, do so concurrently as far as is possible.
results = []
client.concurrently do |api|
results << api.get('post/1')
results << api.get('post/2')
results << api.get('post/3')
end
results
# => [#<WpApiClient::Entities::Post>, #<WpApiClient::Entities::Post, #<WpApiClient::Entities::Post>]
Testing and compatibility
This library comes with VCR cassettes recorded against a local WP installation.
If you want to make your own VCR cassettes, use these scripts.
To run the tests, invoke rspec
.
The repo contains cassettes built from different versions of WP. To run against these cassettes specify WP_VERSION at the CLI.
WP_VERSION=4.4 rspec
WP_VERSION=4.5 rspec
# etc
Postmeta
Metadata discovery was removed from WP-API in 2.0 beta-13 and you need to restore it manually. More details.
Structure
Public Objects
WpApiClient::Client
Accepts a WpApiClient::Connection
and exposes a #get
method.
Pass a URL into #get
and it will do its best to return usable data.
The second parameter accepts an optional hash of query params.
WpApiClient::Connection
Initialize with an API endpoint like http://localhost:8080/wp-json/wp/v2
, then
pass into a new client. Faraday options might be pulled out of here in the future.
Internal Objects
WpApiClient::Collection
Wraps a set of WpApiClient::Entities
in an Enumerable
interface and provides next_page
and previous_page
methods. Pass these into @api
and it will give you back the
data you want
next_page = @api.get(posts.next_page)
# => #<WpApiClient::Collection:0x00bbcafe938827 @resources=[#<WpApiClient::Entities::Post...
WpApiClient::Entities::Base
Base class for Post
, Term
, Image
and Taxonomy
, so far. Not all methods are implemented.
Other
Thanks WP-API!