Etsy API

How to use the Etsy API by using the OpenAPI spec to generate code for Java Spring Boot.

Introduction

During Covid, I setup an Esty store to sell custom 3d printed labels, I was manually setting the colour and text for each one.

Seems that I had found a niche and was selling labels, but after the 50th label I realized that I needed a way to automate the process.

Approach and Assumptions

The approach to automating the process was to use the Etsy API, OpenAPI Generater and Java.

The following are assumptions and dependencies:

  • Etsy API 3, release 1.0.0
  • OpenAPI Generator, openapi-generator-cli-6.2.0.jar
  • Java 8
  • MacOS, 12.6 (Monterey)

The Etsy API

Etsy provides an API to most of their functions, using the OpenAPI specification. Formerly known as Swagger, the OpenAPI provides definition of the RESTful web services in a json or yaml file.

The OpenAPI specification allows the API provider to share a language independent document of the API functionality. The clients using the API can also use the specification document to generate code that accesses the API.

Generating Java Code

“Use what you know” is a common refrain, so I used Java and SpringBoot to create a Java project that hosted the generated code based on the OpenAPI definition.

If you are looking for a Java client lib for Etsy, the generated Java that I created is available here:
https://github.com/gordonturner/etsy-open-api-client

This Java client lib was created from version 1.0.0 of the Etsy openapi.json file.

Download the OpenAPI Generator from:
https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.2.0/openapi-generator-cli-6.2.0.jar

This assumes you have at least Java 8.0 installed, for more details see:
https://openapi-generator.tech/docs/installation/#jar

To generate the code, run the following command:

java -jar openapi-generator-cli-6.2.0.jar generate \
-i https://www.etsy.com/openapi/generated/oas/3.0.0.json \
-g java \
-o ./etsy-open-api-client \
--skip-validate-spec \
--group-id com.gordonturner.etsy \
--artifact-id etsy-open-api-client \
--artifact-version 1.1.0 \
--type-mappings=integer=Long,int=Long

It uses the OpenAPI spec file at https://www.etsy.com/openapi/generated/oas/3.0.0.json

Changes: Integers to Longs

Perhaps inevitably there are some manual changes and tweaks needed, often because the spec file was generated from one language and you are using it to generate code in another.

One of the first things I had to update was the size of some of the numeric elements. They were defined as Integers but the data returned from the API would not fit in the Java Integer object, so I had to add the type-mappings parameter in the generate command above.

This changed variables such as shopId, paymentIds, receiptId etc.

Changes: Enums

The next change was that the values returned from the Etsy API for org.openapitools.client.model.ShopReceipt.StatusEnum where mixed case values, and the generated definition expected all lower case.

I opened a GitHub issue (https://github.com/etsy/open-api/issues/469), but in the mean time I updated the generated Enum file to expect mixed case.

https://github.com/gordonturner/etsy-open-api-client/blob/main/src/main/java/org/openapitools/client/model/ShopReceipt.java#L89

What functionality does the Etsy API have?

All this is great, but what can I do with it?

Well, I used it to create a private website that lists all of the open orders and then added a button to create an order directory and add a data.yaml file describing each order’s label (model, label text and colours).

Then I can then read in that data in Fusion 360, to automate the creation of the printer stl files.

Additionally, I can also see what the actual revenue from an order is, excluding the Etsy and shipping fees.

Conclusion

Prior to OpenAPI specification, the consumption of API services was a real chore. Now the effort to keep things (mostly) up to date is much lower and enables custom solutions to stream line workflows.

Comments are closed.