Using the WooCommerce REST API – Introduction February 21 2014

My favorite feature from the recent WooCommerce 2.1 release is the REST API. I may be a bit biased, since it was my core contribution during the 2.1 release cycle, but it lays important groundwork. A platform like WooCommerce is strongest when shop data can be pushed or pulled from other systems, like a mobile app (spoiler: a WooCommerce iPhone app is coming soon!) or a complex integration with a backend accounting system.

In this series we’ll dive into each aspect of the WooCommerce REST API, starting with a general overview of the API, followed by a post on each type of resource that’s available. Before we begin, remember that the REST API is only available in version 2.1 or greater, so if you’re on an older version you’ll need to upgrade first. Let’s get started!

Overview

The REST API is read-only, with the exception of a single endpoint for updating order status. Data is available in either JSON (default) or XML format. There are 5 primary resources, each with a related set of endpoints:

  • Coupons
  • Customers
  • Orders
  • Products
  • Reports

The API can be accessed at https://www.example.com/wc-api/v1 — note the v1 version which takes a first-order position in every endpoint URL. This will only change for major releases and backwards compatibility is planned for at least one major version back, so you can safely build integrations against the version without worrying about a newer version of WooCommerce breaking your code :)

You can access the API over HTTP or HTTPS. I strongly recommend using HTTPS wherever possible, as it makes authentication significantly easier. The API Index (discussed below) will indicate if the site support SSL or not.

Responses

The default response format is JSON, which can be changed to XML by setting the HTTP ACCEPT header to application/xml. A successful request will return a 200 OK HTTP status, while unsuccessful responses will return non-200 statuses — a detailed listing of errors is available in the REST API documentation.

Authentication

There are two ways to authenticate with the API, the easy way (over HTTPS) or the hard way (over plain HTTP using OAuth). If you’re developing an integration designed to work with any WooCommerce store, you’ll need to support authentication schemes, as you can’t guarantee that every store will have SSL enabled. The API Index endpoint will indicate if the site supports SSL.

With that in mind, login into your WP-Admin and go to your user profile to generate your API keys. You should see something like this:

woocommerce-rest-api-keys

Keys inherit the permissions of the user that generates them, so if you’d like to have more granular control over the permissions you can create a new user specifically for the API.

Over HTTPS

Simply use HTTP Basic Auth by providing the API Consumer Key as the username and the API Consumer Secret as the password:

$ curl https://www.example.com/wc-api/v1/orders -u consumer_key:consumer_secret

If you’re manually setting the HTTP Authorization header, remember that you must Base64 encode the keys first, like so:

php > $authorization = base64_encode( $consumer_key . ':' . $consumer_secret );

Over HTTP with OAuth

HTTP Basic authentication cannot be used over plain HTTP as the keys are susceptible to interception. The API uses OAuth 1.0a “one-legged” authentication to ensure your API keys cannot be intercepted. This process involves generating a signature and including it with your request. The API then generates it’s own signature and compares it against the one provided. If they match, the request is authenticated.

The process for generating this signature is not difficult, but it must be followed exactly. The best way is to use an existing library in your language of choice to handle OAuth authentication. If you’re a glutton for punishment and want to generate the signature manually, have a look at RFC 5849 which describes how to generate the signature.

Parameters

Most API endpoints accept optional parameters passed as HTTP query string parameters, e.g. GET /orders?status=completed — but the most important parameter is the filter parameter. This parameter is used for date filtering, searching, and pagination. See the full list, along with examples, in the REST API documentation.

API Index

The API index provides information about the store, as well as a listing of available endpoints. No authentication is required to access the index. The most important property is ssl_enabled which will indicate if SSL is available or not. A sample response is available in the docs.

Additional Reading

Next in the series we’ll detail how to get order information, along with how to update the status of an order. Until then, here’s some additional reading about the API:

The post Using the WooCommerce REST API – Introduction appeared first on SkyVerge.