11 Feb 2021
I don't work with WordPress any more. If you would like to take over maintenance, please open an issue!
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.
gem install wp-api-clientAnd
require 'wp_api_client'# 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...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 etcYou 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...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...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.
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::RelationNotDefinedThe 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.postsProvide 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_clientProvide 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_clientWP-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>]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
# etcMetadata discovery was removed from WP-API in 2.0 beta-13 and you need to restore it manually. More details.
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.
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.
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...Base class for Post, Term, Image and Taxonomy, so far. Not all methods are implemented.
Thanks WP-API!