API Versioning for Connect v2 – Square Corner Blog – Medium


We’ve got an exciting update coming for our Connect v2 developers! We have released versioning for all Connect v2 endpoints for Square’s APIs. This will allow us to deliver more functionality and features faster than ever before. No need to worry though, our APIs will remain backwards-compatible and will allow you to upgrade when you’re most comfortable. This means you can safely continue using the Square APIs you already love, but allows us to bring you new or improved features without breaking your code.

What does this mean for me?

If you don’t want to upgrade your integration or use the latest and greatest, then it means you can stick with the version of the API that you’re currently using. If you do want to upgrade, you can easily test things out by forward setting your Square-Version header to your desired version.

How do I know what version I am on?

You can always check your developer dashboard. You can also check the response from calling an endpoint and see what your Square-Version header is set to. When you create your app, your default version (the version currently set for your application) is set to the most recent version of the API. This means that if you don’t explicitly specify the version of the API to use when making requests to Connect v2 endpoints, your default version will be used. So if the most recent version of the API is 2018-07–04 and you created your app on 2018-07-10, then you’ll be set to version 2018-07–04.

Why are you doing this?

This lets us deliver more functionality to developers while preventing negative impacts that upgrading APIs can have on developers who have already implementations.

Do I need to upgrade my SDK?

If you are upgrading your API version, then you’ll need to upgrade your SDK version as well. Certain versions of our SDKs will always correspond to a specific version of the API, so its best to test the latest version of the API with the latest version of the SDK. This means that as new versions of the API are released, so are new versions of our SDKs. The SDK version will follow the format 2.20180704.0 to correspond to version 2018-07–04 of the API. You’ll always know what version of the API the SDK is using by just looking at the SDK version.

The great benefit here is also that even if you don’t remember to go into your dashboard and upgrade your app’s default API version, the SDK will handle explicitly setting the Square-Version header to the API version that matches to the SDK. No more thinking about which version to be on, let the SDK do the work for you!

What does this look like?

Note line 4, where we’re explicitly setting the “Square-Version” header.

We are really looking forward to delivering new and improved functionality to developers. Having API versioning is a key step to getting this into the hands of developers. We can now give developers the features they want more rapidly while also not breaking things for existing implementations. If there are new features that you really want or things that you want improved, come join us in our Slack community or post on StackOverflow with the tag square-connect so that we can hear from you.



Source link