https://api.gogrid.com/api

All input information is transmitted via query parameters in an HTTP request.

• For HTTP GET calls this information is passed via the query string.
• In HTTP POST calls, this information is passed in the request's body.
• All request data must be URL encoded.
• Request parameters are typed. For more information, see Types.

The following query parameters are common to all API calls:

All API calls must be transmitted as encrypted HTTPS calls. GoGrid does not accept unsecured, unencrypted HTTP calls.

API Key

You need to obtain an API key through your GoGrid account before your can start submitting requests to the GoGrid API. To do this log in to your GoGrid account at http://my.gogrid.com. Once you have logged in, click on the My Account button and then the API Keys tab.

Click the Add Key button and enter a value for shared secret. Once you click OK, an API Key will be generated and displayed on the page. Keep track of your API Key and shared secret values and be sure to keep them confidential as they will allow you to make authorized API requests against your GoGrid account. If an outside party obtains access to your API Key or shared secret, they will be able to make API requests that could affect your servers. If you think your API key or secret have been compromised in any way, then you can and should delete that API Key and generate a new one. Any client code you have written will need to be updated to use the new API key and secret.

MD5 Signature

Each request must be signed. A valid signature is determined by examining a sig parameter from the query string of the request. The sig value is calculated by generating an MD5 hash made up by concatenating the API key, the API user's shared secret, and a UNIX timestamp reflecting the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) when the request is made. A ten-minute wiggle is permitted on either side of the current timestamp on the GoGrid REST API server to allow for reasonable clock drift.

In PHP, the following code generates a valid sig query parameter:

<?php
$apikey = 'skfdikv22l2l30slasl323l302lqjss';
$secret = 'This is my secret';
$timestamp = time(); 
$sig = md5($apikey . $secret . $timestamp);
?>

• Note - Properly signing a request requires that the clock on the client machine be synchronized with the server clock. The easiest way to achieve this is using a time synchronizing service such as NTP or Windows Time Service.

All API calls should pass the version they are expecting. The current version is 1.1. The set of available versions is 1.0, and 1.1.

The following is the HTTP request to list all the lookup names (see common.lookup.list) in the system. It is representative of a basic call, requiring the common query parameters, api_key, sig, and v, be properly specified.

https://api.gogrid.com/api/common/lookup/list
  ?lookup=lookups
  &sort=name
  &asc=true
  &api_key=SK1mndkKSjsALKSExdsj30
  &sig=Lsmdfj3kw99sdklnasdkjhds
  &v=1.0

JSON

Java Script Object Notation is a lightweight, easy to read and parse format.

• json.org - Has a plethora of information with syntax documentation and links to different language JSON parsers.
• Wikipedia JSON Article - Wikipedia article on JSON.

XML

eXtensible Markup Language is a standard web format. Parsers are available in all programming languages.

• Wikipedia XML Article - Wikipedia article on XML.

CSV

Comma Separated Value format is one of the oldest structured data formats. CSV is easy to parse, but is flat and does not easily allow an object hierarchy.

• Wikipedia CSV Article - Wikipedia article on CSV. Good documentation regarding this format.

There are two kind of errors; client errors and server errors. Client errors occur when a client request is not properly submitted. Server errors occur when an unexpected condition arises during execution of the request on the server. Client code can check the HTTP response status code to detect errors and in some cases, such as 400 errors, the body of the error response will contain more detail for the error.

For client errors, the HTTP response status code will be set to 400 (BAD_REQUEST) so that client code may quickly determine if the call was successful by simply checking the response status.

For server errors, the HTTP response status code will be set to one of several 5xx codes, such as 500 or 596.

Successful requests will have HTTP response status codes of 200.

Client Errors

400 - IllegalArgument

This error occur for several reasons, including not provided required parameters or specifying invalid values for parameters. The specific reason for the error is described in the body of the error response.

401 - Unauthorized

This error will occur when your request has the wrong Access Controls. If your API key has only read only status and you try to update the grid, you will get a 401 Unauthorized error.

403 - Authentication Failed

This error will occur when your request is not properly signed. Make sure that you have a valid API key and secret and that you are properly generating a request signature. Ensure that the clock on the computer from which you are making the request is synchronized with the GoGrid API server

404 - Not Found

This error will occur if you have specified a method that does not exist or any other URL does not exist on the API server.

Server Errors

500 - UnexpectedError

This type of error will only occur when there is an unanticipated problem with the server. These types of errors indicate an internal system problem. Depending on the severity of the error and whether not it is blocking your development, report the error to GoGrid support by emailing the response to apisupport@gogrid.com.

Here is an example of an unexpected error :

<gogrid>
  <response method="/grid/server/get" status="failure">
    <summary total="1" start="0" returned="1"/>
    <list>
      <object name="error">
        <attribute name="errorcode">UnexpectedError</attribute>
        <attribute name="message">An unexpected server error has occurred. Please report this error to apisupport@gogrid.com. Error Message : Expected a populated object list.</attribute>
        <attribute name="attribute"></attribute>
      </object>
    </list>
  </response>
</gogrid>