Using the Woocommerce API

If you want to host your own webshop, Woocommerce is a popular option. You can install it as plugin to WordPress. Using plugins your shop can be extended with different payment options as well as various other functionality.

Woocommerce is written in PHP, and exposes an REST-API. I wanted to play around with the API, see if I can add products and do other things. Woocommerce provides extensive documentation on their REST-API. A few client libraries are added for various languages, but unfortunately not for my favorite language Scala, and neither Java. But the REST-API documentation seems generated based on some schema, so couldn’t I just generate my client?

Rest-API

After short investigation, I found out that, if enabled, WordPress exposes a rest-api. For example, see the rest-api of my website, which uses WordPress too: www.software-creation.nl/wp-json . WordPress provides namespaces and has schema information on all the plugins that are installed. Here’s portion of another WordPress-site, which has the Woocommerce plugin installed:

{
  "name": "Liberactiva",
  "description": "passie voor het boek",
  "url": "https://www.liberactiva.nl",
  "home": "https://www.liberactiva.nl",
  "gmt_offset": 1,
  "timezone_string": "Europe/Amsterdam",
  "namespaces": [
    "oembed/1.0",
    "document-generator-for-openapi/v1",
    "jetpack/v4",
    "wc-admin",
    "wc-analytics",
    "wpcom/v2",
    "wc/store",
    "wc/v1",
    "wc/v3",
    "wc/v2",
    "wccom-site/v1",
    "wp/v2",
    "wp-site-health/v1"
  ],

The namespace wc/store belongs to Woocommerce.

Openapi-spec of Woocommerce

Now, can I have that schema available in something that allows me to generate the api-client? The documentation of Woocommerce is generated automatically, surely it should be easy to generate an openapi spec?
There are a few plugins to generate openapi specs, such as this one: wordpress.org/plugins/document-generator-for-openapi . After installing I can generate an openapi spec for any plugin by referencing it’s namespace, including the openapi spec for Woocommerce, using various namespaces, of which I assume wc/v3 is exposing the latest version. The openapi-spec is in JSON format ans uses openapi 3.1.0 . Most openapi viewers seem to support only openapi 3.0.x at most, but by manually changing the version to 3.0.0 I manage to be able to view the document the Swagger Editor, although I still get a few errors

Generating openapi spec via WordPress

Seems the main difference between openapi 3.1.x and 3.0.x is that types can be collection (list) in the latest openapi version. As quick-fix I just changed the types from list to most appropriate single type like this. Not to make to manual changes in a generated document, I ended up forking the original plugin, but I hope I can merge the changes back in to the original plugin.

The resulting document is available my github-repository: woocommerce-openapi-3.0.x.yml.

Alternative, generating the openapi spec from Woocommerce source

Generating via a plugin seems like a good start, could I also generate the openapi spec from the Woocommerce documentation?
I’ll start with downloading the Woocommerce source code. Building is pretty easy but now where to continue? There’s generated documentation, so most likely part of the build process would generate documentation. And I’d think I could extend that part of the build process to generate some openapi document as well. The api module contains a Typescript api client that definitions of the model in typescript . Well for now giving up and will use the original openapi spec, but not for posting a question on the woocommerce forum.
(2021-12-02), I got answer back, they suggested looking at the woocommerce-rest-api-docs . Turns out the api-docs are in markdown, built using a tool called slate. Turning markdown into a formal specificication seems a bit hard, so I’ll stick to the openapi document as mentioned above.

Conclusion

If all webapi provided an interface described in openapi, swagger, graphql or similar, integrating with such api would be a lot easier. Woocommerce at least has a proper api documentation, and with some effort I managed to create an openapi-document. Next posting, I will try to generate a client based on the openapi-document.