MerchantOS API Version 2.0

[Nathan Horter]

In the coming weeks we are going to be releasing changes to our API that will be changing some default functionality. Concurrent with those changes we will be increasing our API version to 2.0. For a limited period of time we will continue to be supporting version 1.0 API behavior.

In order to continue to use our version 1.0 API you must send an Accept header with the value application/vnd.merchantos-v1+xml (application/vnd.merchantos-v1+json) or add a “version=1” parameter to your request. We strongly recommend that going forward you specify an API version in your requests. If you do not specify a version you will receive the latest API version.

Changes in MerchantOS API Version 2.0

• 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, DELTE) 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.

• 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.

We are informing you ahead of these changes to give you time to set your API version ahead of time and hopefully implement changes to your API clients so that they will be able to take advantage of the new features we are rolling out.

As always you can post API questions on our MerchantOS API Developers Google Group: http://goo.gl/m39LF

[Fabio]

A couple of questions for this release.

Will it be possible to request a contained object of a contained
object?

I just tried a request with ...&version=1 with the current version and
I get an error.
Will there be a way to request the available version, so that we will
know when to implement upgrades or will there be a grace period with
the new api. You mentioned the default behavior is using the
latest....

Thanks
Fabio

On May 15, 5:30 pm, Nathan Horter <n...@merchantos.com> wrote:
> In the coming weeks we are going to be releasing changes to our API that
> will be changing some default functionality. Concurrent with those changes
> we will be increasing our API version to 2.0. For a limited period of time
> we will continue to be supporting version 1.0 API behavior.
>
> In order to continue to use our version 1.0 API you must send an Accept
> header with the value application/vnd.merchantos-v1+xml
> (application/vnd.merchantos-v1+json) or add a “version=1” parameter to your
> request. We strongly recommend that going forward you specify an API
> version in your requests. If you do not specify a version you will receive
> the latest API version.
>
> Changes in MerchantOS API Version 2.0
>

>    - *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, DELTE) 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.
>

>    - *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

[Nathan Horter]

You will be able to request related objects so that you can get a structure like what we deliver right now.

We don't quite have the url version parsing ready to go, but we will have that out before we change the version.

I'll look into a way to report the available API versions. It would be best to implement clients that make requests to a specific API version so that they don't get unexpected behavior when we release a new version. Eventually the older versions will be deactivated in favor of the latest API version.

Nathan Horter
MerchantOS
Direct: (866) 554-2453 x95
na...@merchantos.com
www.merchantos.com