(Currently in alpha release - use in production at your own risk)
A Wordpress API client that works both in the browser and in Node. Tiny footprint, > 95% code coverage, browser tested down to IE11, tree shakable CJS and ES6 builds, expressive syntax.
-
- Fetch client
- Fetch React
- Comming soon...
There are great alternatives such as wpapi and yllet although both of these projects have issues:
- Long unresolved browser issues
- Bloated packages size
- No tree-shakable ESM or CJS build available
- Opinionated API that attempts to do more then is needed.
- Lack of automated browser testing and coverage
We intend to build and support a lean and well tested packages that fit into the modern ES6 javascript ecosystem.
The fundamental tool in the wp-headless ecosystem is the API client.
Yarn
yarn add @wp-headless/clientNPM
npm install @wp-headless/clientCreating a client instance bound to the endpoint of your Wordpress install:
import Client from '@wp-headless/client';
const client = new Client('https://demo.wp-api.org/wp-json');Fetching posts:
// post with id 123
const post = await client.posts().get(123);
// post with slug 'hello-world'
const post = await client.posts().slug('hello-world');
// All posts
const posts = await client.posts().get();
// filtered posts
const posts = await client.posts().get({
per_page: 10,
orderby: 'title',
search: 'Dog fetches bone'
});Fetching pages is the same as above, simply change the resource endpoint as follows:
// page with id 456
const page = await client.pages().get(456);The client provides the following API resource methods:
client.categories()client.comments()client.media()client.statuses()client.posts()client.pages()client.settings()client.tags()client.taxonomies()client.types()client.users()
These resource methods are simply syntax sugar for setting the path and namespace to an API resource. Therefore the following are equivalent:
const posts = await client.posts().get(123);const post = await client.get('posts/123');Adding custom resource methods is easy (example WooCommerce REST API), the following would fetch the enpoint http://demo.wp-api.org/wp-json/wc/v2/products:
client.products = () => client.namespace('wc/v2').resource('products');
const products = await client.products().get();Of course you could simply also do the following:
const product = await client.namespace('wc/v2').get('products/123');As you can see building requests is as simple as setting the namespace(), resource() and the HTTP method; get(), post(), put(), patch() or delete().
Client instances also provide access to HTTP methods to access API resources.
client.get(); // Http GET
client.create(); // Http POST
client.update(); // Http PATCH
client.delete(); // Http DELETEFor example:
// create a post
const post = client.posts().create({
title: 'Dog fetches ball',
content: '<p>then he brings it back</p>'
});
// update the post
const post = client.posts().update(post.id, {
excerpt: 'Its just what dogs do...'
});
// delete the post
client.posts().delete(post.id);You can pass request parameters as an object to any of the above methods:
// REQUEST URI https://demo.wp-api.org/wp-json/wp/v2/posts
// REQUEST BODY { title: 'Hello doggy', content: 'fetch a bone' }
const post = client.posts().create({
title: 'Hello doggy',
content: 'fetch a bone'
});Or with a get request
// REQUEST URI https://demo.wp-api.org/wp-json/wp/v2/posts?per_page=10&status=draft
const post = client.posts().get({
per_page: 10,
status: 'draft'
});Its also possible to set global params that will be sent with each request:
// Sets a single param key/value
client.param('per_page', 20);
// Merges an object with current global param values
client.param({
per_page: 20,
orderby: 'title'
});To retrieve global params:
// Single value
client.param('source'); // wp-headless
// All values
client.params;WordPress API supports embedding of resources and instead of having to provide ?_embed=true as a param on every request you can simpley use embed() before any request methods.
More about WordPress API embedding can you read here.
const posts = await client
.posts()
.embed()
.get();Or globally for all requests:
client.param('_embed', true);
const posts = await client.posts().get(); // now embededSometimes its helpful to have expressive methods that wrap the underlying api, making code more readable and clean.
slug(string: slug)
Slug method is a shortcut to fetch a single post, custom post or page via its post_name (slug) attribute.
const post = client.page().slug('sample-page');
// ...equivalent to
const post = client
.page()
.get({ slug: 'sample-page', per_page: 1 })
.then(posts => posts[0]);more
We endevour to add a minimal set of sugar to this library, keeping it small, lean and bloat free is imperative.
The architecture of Fetch allows you to specify your own transport layer such as fetch or axios. This allows devs to use a library that they are familiar with, and perhaps are already using in their app, saving bundle size.
The client uses the Fetch API Standard to make requests. This is supported in all modern browsers and newer versions of Node.
To support older browsers you will have to implement a polyfill such as isomorphic-fetch or (isomorphic-unfetch)[https://github.com/developit/unfetch/tree/master/packages/isomorphic-unfetch]:
yarn add @wp-headless/client isomorphic-unfetchimport 'isomorphic-unfetch';
import Client from '@wp-headless/client';
const client = new Client('https://demo.wp-api.org/wp-json');If you would like to use a different transport layer such as axios or superagent you only need to write an adapter that adheres to interface of the Transport class found in the client package. To use this layer pass your custom transport as the second argument to the Client:
import 'isomorphic-unfetch';
import Client from '@wp-headless/client';
import AxiosTransport from 'my-custom-axios-transport';
const transport = new AxiosTransport();
const client = new Client('https://demo.wp-api.org/wp-json', transport);We provide (and reccomend) React hooks that take care of your entire darta fetching life cycle. From fetching initial data, caching, optamistic updates, mutating and refetching - its all covered in an incredibly easy to use hook api. Thanks in a large part to Zeit's swr
Yarn
yarn add @wp-headless/reactNPM
npm install @wp-headless/reactimport React from 'react';
import { usePost } from '@wp-headless/react';
export const Post = ({ postId }) => {
const { post, fetching } = usePost(postId);
return <h1>{post.title.rendered}</h1>;
};Examples of usage in a real world application can be found in the examples folder.
Thanks to BrowserStack for lending us their amazing infrastructure to give us automated browser coverage
Thanks to Drone an incredible pure docker CI/CD platform built on golang for building our stack!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent