Previous (API Getting Started Guide)
Next (Common API Call Patterns)

Contents

Overview

All API calls are transmitted over HTTP GET or POST Requests. API calls consist of both an HTTP request, which is the API input and its response, the API output. The following is a sequence diagram of a GoGrid API call:

File:ApiAnatomy.png?

To get started using the API, you must generate an API key through the GoGrid customer portal. Under My Account > API Keys, you will find a link to add an API key. While the API Key will be dynamically generated, you must choose a shared secret and role that are bound to the API Key. The shared secret is a secret phrase shared with GoGrid that will be used to authenticate API calls.


HTTP API Request

All input parameters to the GoGrid API are transmitted as HTTP Query Parameters. Both GET and POST Requests are accepted.

API Server URL

Common Input Request Query Parameters

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:

Required Name Type Description
Required api_key string An API Key generated by GoGrid.
sig string An MD5 Signature that signs each and every API request. Instructions on how to generate this signature can be found below.
v string The version of the API. For more information, see API Versions.
  • For version 1.0, set parameter to 1.0

Security

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

Authentication

API Key

You need to obtain an API key through your GoGrid account before you can start submitting requests to the GoGrid API. Follow the steps below to obtain an API key:

  1. Log in to the customer portal.
  2. Click on My Account > API Keys.
    File:API.png?

  3. Select Add an API key from the API Menu.
  4. A pop-up window appears. Enter a value for the shared secret. Select the role and status from the drop-down menu.
    Add API key.png
  5. Click Save. 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, 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.

Version

All API calls should pass the version they are expecting. See the API Version Log for more information.

Sample HTTP Request

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 that 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.5

HTTP API Response

Output Formats

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.


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.


Error Responses

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 the 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 occurs for several reasons, including not providing 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 only has 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 or not it is blocking your development, report the error to GoGrid support by submitting a support case through the customer portal.

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 GoGrid. Error Message : Expected a populated object list.</attribute>
        <attribute name="attribute"></attribute>
      </object>
    </list>
  </response>
</gogrid>


Previous (API Getting Started Guide)
Next (Common API Call Patterns)
Personal tools