Responses

When a response comes back, there are two pieces of information to consider:

• HTTP Status code - this tells you at a protocol level what the status of the response is.
• Response Payload - this is the body of the response. It is in a standard format that will give you the application level status, the results, and if applicable, any errors.

Response Formats

All responses are returned using JSON. JSON is a lightweight serialization language that is compatible with many different languages. JSON is syntactically correct JavaScript code, meaning you can use the Javascript eval() function to parse it.

HTTP Status Codes

Our REST API uses standard HTTP status codes to indicate success or failure of API calls. Like with most topics, Wikipedia has good resources on HTTP Statuses, but here are the basics of what we will return:

The non-20x status codes above correspond with an error of one type or another. Below we detail the error responses.

Response Payload

Each API response is wrapped in a standard payload that contains the results of the API call, plus some additional useful information and metadata, such as the total count of records and the type of the result object. Here’s an example of a response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "status": "success",
  "count": 2,
  "type": "LoadServingEntity",
  "results":[ {
    "lseId": 2756,
    "name":"Georgia Power Co",
    "code":"7140",
    "websiteHome":"http://www.georgiapower.com/"
  }, {
    "lseId":1,
    "name":"City of Augusta",
    "code":"1000",
    "websiteHome":null
  }]
}

The above shows a successful response back from the call. In this case the result type is LoadServingEntity and there are two results. Note that the results are always an array even if you only requested one object.

The count property tells you how many items matched the search criteria of your request. Note that we currently limit the count property to a maximum of 100,000. You should actually interpret a count of 100,000 as “100,000 or more”. Use the count property in conjunction with Pagination Request parameters.

Response Payload Changes

From time to time, we may add to the set of fields that is returned from a particular endpoint in the API. In general, these new fields will only appear if you specify that the API should return the extended set of fields. However, API clients should always be prepared to handle (i.e. ignore) any new object properties that they do not recognize.

Errors

Errors are communicated to the client in the payload of the response.

Errors in the Response Payload

The standard response payload can contain errors. This will give more finely grained details about what specifically caused the error or errors, which should allow you to respond appropriately. This might include displaying validation messages to your users or changing the request at runtime.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "status":"error",
  "count":2,
  "type":"Error",
  "results":[{
    "code":"NotNull",
    "message":"An appKey must be supplied",
    "objectName":"requestSignature",
    "propertyName":"appKey"
  }, {
    "code":"NotNull",
    "message":"An appId must be supplied",
    "objectName":"requestSignature",
    "propertyName":"appId"
  }]
}

Error Type Definition

The type Error has the following data definition:

List of Error Codes

The code in the Error can be any of the following: