The Foxy Hypermedia API!

This Hypermedia API is designed to give you complete control over your FoxyCart store. Anything you can do in the FoxyCart admin, you can also do through this API which means you can embed Foxy into any application. As a hypermedia-driven API, there will always be loose coupling between your client and our server allowing both of us to evolve independently. If you have any questions, please contact us.

You can start with the Authentication section which will walk you through creating your own Foxy hAPI OAuth client for your project, creating (or connecting) to your FoxyCart user and store.

From there, you can run through our Tutorials to get a feel for working with the hypermedia and updating your store resources.

We have some great Tools for you, including the HAL Browser.

The Cheat Sheet has all the details you need on how to work with this hAPI include the media types we support, our authentication system, and the framework we use for selecting, creating, editing, and deleting resources. It also has some nice goodies for sorting, filtering, and zooming into embedded resources.

Hypermedia APIs deal with resources represented as uniform resource identifiers (URIs), each accessed via link relationships. Our API Reference section includes documentation for each resource including the actions which can be performed on that resource, the properties of that resource, and example representations of the resource in the various content types we support.

For more background information on the style of documentation we're currently using, please see Luke Stokes' medium post or Kin Lane's follow up post.

Some background for those not familiar with using Hypermedia APIs

One of the keys to a successful Hypermedia API is proper use of caching (all clients should take advantage of local caches and ETags). If you’re not familiar with hypermedia APIs, things may seem a bit “chatty” at first, but that’s where your client’s local cache comes into play.

Start with the home page and cache it. On the next request (to that or any resource you've already visited), be sure to send that ETag along with an If-None-Match header so you can use your cache entry in the event of a 304 Not Modified response. From there, use hypermedia to navigate to related resources using the links either in the header or the body of the response.

Unlike RPC (remote procedure call) APIs, you shouldn't code to the individual endpoints. We (the server) control those and should be able to change them as needed. So don’t code to the URLs. You should code to the link “rel” tags which define the relationships to the current resource. These should not change, though we may introduce new links (and new rels) at any time, so don’t assume they will be in a specific order.

Because the primary use-case of our API is to provide CRUD functionality much like our current admin user interface, our API has more of a CRUD feel than many REST experts would recommend. We’re not suggesting this is the best way to do all REST APIs, but it happens to fit our problem domain, so here we are.

To view a resource or a collection of resources, use GET. If you’re not sure what you can do with a rel, use the HTTP method OPTIONS. Or, if you just want the links so you can navigate to a different resource, use HEAD.

To create a new resource, POST to a rel that represents a collection of resources. To modify a resource (in its entirety) use PUT. If you just want to change a few properties on the resource, use PATCH (note, you may need to include the X-HTTP-Method-Override: PATCH header with a POST if your http client doesn’t yet support PATCH).

We feel this mapping from CRUD to HTTP verbs is pretty straightforward so we’ve avoided many different rels with the same href. Some argue rels should more directly map to specific user activities, but we haven’t gone that route and feel a layer on top of a purely REST system might be more appropriate to better map to user affordances.