If you don’t know what an API is; ignore this and carry on.
If you’ve written an integration to the MerchantOS API or have had an outside developer write an integration take note! The API will change to version 2.0 this Wednesday night (8/8/12). Your integration may break if you are not prepared.
Here are the primary changes we are making in version 2.0 and how you can work around them to keep your current integration working:
- shallow by default: Currently you can specify a shallow parameter on our API to have only the requested object, but none of its children or related objects returned. We are going to be setting this as the default behavior. To receive related objects you will need to specify a “load_relations” parameter with the related objects to load (see below).
- readonly by default: By default all read (GET) requests will be using our readonly backend. For applications that are only reading or aggregating data there will be no changes. For applications that write data and then read that data out, be aware that there is a replication delay between our servers where the write requests (PUT, POST, DELETE) are processed and the servers where reads (GET) happen.
- It is possible to override this behavior by setting the readonly parameter to false (readonly=false). Only do this if you need to read data immediately after writing it. Abuse of non-readonly reads can result in your application being rate limited or blacklisted.
- Responses from writes are always realtime. When you write data you get the object that was created/updated back as a response. That data is always a real time response to your write. No need to worry about readonly=true.
- load_relations search parameter: As mentioned above a new search parameter is being added that allows you to load related objects dynamically. Using this option you can load only the related objects that you need to get information from. All other related objects will not be loaded, allowing our API to respond to your request more quickly. load_relations=all will have the same behavior as the 1.0 version of the API.
- JSON format changes: We are also improving our JSON emitter to improve its performance. In addition we are changing how single objects are returned in JSON format. Currently they are returned as bare objects. After the API version 2.0 changes they will be returned in an array the same way that multiple objects are returned. We hope that this change will simplify parsing JSON from our API.
- We are also improving the layout of tags in our JSON responses so that they are not as verbose. Again we hope this will improve client parsing.
Workarounds and Fixes:
- Version=1: The easiest work around is to set your version to 1. Adding a GET parameter of version=1 will accomplish this. You can also send a version header in the form of a specially formated Accept header like: application/vnd.merchantos-v1+xml (version 1 with xml output). Another example would be: application/vnd.merchantos-v2+json (version 2 with JSON output)
- load_relations=all: Set load_relations=all as GET parameter to your query to load it with all relations just liket he default behavior in version 1.0. If you have an integration that needs to read a lot of data from us we recommend you do not use load_relations=all. Instead use load_relations=[set of relations you really need]. That will allow us to handle more of your requests.
- readonly=false: If you need to write data and then read with those changes applied in real time set readonly=false as a GET parameter. As noted above this can get your application/IP rate limited or blocked if you abuse it.
The API changes also include OAuth 2.0 for authentication. This allows us to set a per client rate limit. If you need a higher rate limit than 10 requests per minute you will need to implement OAuth 2.0 for your API authentication. We will then review your integration and increase your rate limit if you meet our quality standards.
Eventually we may phase out other authentication methods so it’s a good idea to implement OAuth 2.0 now. It also makes for a better user experience if you have end users setting up your integration (no more cutting and pasting API keys).
API Version 1.0 Sunset
We will sunset version 1.0 of the API when we release version 3.0. You should plan to make the changes necessary for version 2.0 compatibility even if you plan to use version 1.0 for now.
Why The Changes?
We’ve had some big challenges with our API around scaling. It’s easy for a programmer to write a loop and eat all our server resources. These changes are moving us towards a more scalable API.
Subscribe To The Developer Group
If you have an integration that uses our API, please subscribe to our Google Group.