This version includes changes to increase API performance under certain circumstances, and a change that allows GeoOp partner accounts to manage their child accounts using the API. This is also the first time that two versions of our API will be simultaneously supported, according to our versioning policy.

GeoOp's API versioning policy

GeoOp's policy is to keep old versions of the API available for 6 months after being officially superseded. 

The intent of this policy is to give external developers sufficient time to update to the current version of the API, while still providing our API team with the flexibility needed to make continued improvements.

In this case, version 1.0 of our API will be available until 7 May 2015.

 

Key Changes

Removal of default recordsCount in GET requests

We have removed the default counting behaviour from GET requests to our API. This means that by default, the metadata object will no longer include the "recordsCount" or "pagesCount" fields, although it is possible to specifically ask for those fields to be populated.

The purpose of this change is to improve API performance and response times. Counting large datasets can contribute to slow database processing speed, which in turn slows down API response time.

If your application requires information on the total number of records, you can use the URL parameter "recordsCount" with a value of "true" in order to receive these two fields. e.g., "http://api.geoop.com/accounts?recordsCount=true".

Note that if you require the recordsCount during a multi-page operation, it is a good idea to ask for the recordsCount on only the first page, to minimize the performance impact. However, in that case, it's generally recommended that you revise your data requirements to use smaller sets of data, or else use an arbitrarily large page size (hopefully, large enough to fit all of your data). 

No hard limit on request page size

You are now able to request arbitrarily many records at one time in an API request, by using the "page" modifier (documented elsewhere). Previously, you were limited to a max of 100 records per request. 

Note that if the request takes too much time to process, our web server may halt processing. Likewise, responses containing very large amounts of data may take some time to download. Therefore, you may still wish to set your page limit to a value which is smaller than the total possible dataset.

This change has no adverse effect on the compatibility of existing API consumer applications. We have therefore decided to release this change in version 1.0, as well.

GeoOp partner accounts using the API

Admin staff of GeoOp partner accounts will now be able to access the data of their child accounts using the API. This was previously only possible using the web console.

Note that it is generally not possible to set up associations between entities belonging to different accounts. For instance, it is not possible to create a Job for child account A using a Client from child account B.

Because of this change, API consumer applications which may be used by GeoOp partner accounts should be built to handle the possibility of receiving data from multiple accounts. You can filter out this data at the level of the API request by specifying a suitable condition in the "where" modifier (documented elsewhere), or you can structure your application to handle receiving such data.