API Versioning for Connect v2

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 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–12 and you created your app on 2018-07–15, then you’ll be set to version 2018-07–12.

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, you may upgrade the SDK version when you are ready. Each version of the SDK is “pinned” to a version of the API, so you never need to worry about the SDK accessing the “wrong” version, even if you change your default. As new versions of the API are released, so are new versions of our SDKs. The SDK version will follow the format 2.20180712.0 to correspond to version 2018-07–12 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?

curl https://connect.squareup.com/v2/locations/{{location_id}}/transactions \
   -X POST \
   -H "Content-Type: application/json"  \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "Square-Version: 2018-07-12" \
   -d '{
    "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "card_nonce": "card_nonce_from_square_123",
   }'

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.

Want more? Sign up for our monthly developer newsletter or come say hi in the Square dev Slack channel!