[ANNOUNCE] API v3 Limited Access

[Matt Graham]

Hi all,

The v3 API is now available in very limited fashion but I want to get this info out to you so you can see how things work and start experimenting with how the framework differs from v2.

Let's start with the public ping call. All this does is return "pong" to tell you if you are correctly submitting the request. Let's try:

GET http://openapi.etsy.com/v3/public/ping

That didn't work did it? All v3 calls will require HTTPS from the outset. So let's try it with HTTPS.

GET http://openapi.etsy.com/v3/public/ping

Sorry, I knew that still wasn't going to work. In v3, the API key needs to be submitted as a header, which makes it kind of awkward to use v3 in a browser. We're going to add some UI to make it easier to use in a browser, but for the purposes of this email, fire up something that lets you set headers in your requests and pass your API key in the "x-api-key" header. In curl, that would be:

curl -H "x-api-key: <your-api-key-here>" https://openapi.etsy.com/v3/public/ping

This time that should have worked and you should have received "pong" as the response. Run it so you can see response headers to see the rate limit information.

Also note that there is no envelope. The value, "pong", is all that is returned. v3 will also use headers for paging. Try this url (still with your api key in the header) which we've implemented for documentation purposes.

GET https://openapi.etsy.com/v3/public/examples/foo

For calls that support paging, the "Link" header will contain information about the next page of data. For calls that return the total number of items in the collection, we will now be passing that in the X-Total-Count header. This information will no longer be a default part of the response to allow us more flexibility to handle paging in an optimized fashion when necessary. Standard paging with 1,2,3,4 can become slow and put a heavy load on our DBs for users with large datasets.

We also plan to support caching via cache headers in the future which you may find helpful for optimizations.

In the call above "public" is what in v3, we are calling a "perspective". A perspective indicates on whose behalf a call is being made. As you can imagine, the Public Perspective is for data that you might see while browsing the site logged out. You don't need to submit any oauth information for making these calls.

The next perspective that I would like to introduce is the Application perspective. The application perspective is used for private access to data about your application. As an example try this url:

GET https://openapi.etsy.com/v3/application

It should return to you a JSON object that contains just your application's ID (don't worry, we'll add more useful fields to this later, for now it's just a stub for demonstration and testing). I'll be announcing some actually useful calls that use the Application perspective shortly.

These are what we have to announce right now. Once I finish the OAuth checks, we will be announcing Member and Shop perspectives, probably in late December. We are still very much in beta / soft launch so for now, this mailing list will serve as the documentation. Please do ask questions and send feedback as it will help drive what to include in the documentation once we get to that point.

Thanks,

Matt