API Conventions

Response Formats

If you make a Kiva API call, you're guaranteed some kind of response. If you make a successful call you'll get an HTTP response with a status 200 OK and the content of that response will usually be data, serialized in some meaningful way.

You can request response data from any Kiva API call in one of two formats, JSON or XML. (Some calls are available in feed-based formats, which we talk about later.) The format depends on which extension you append to the end of your URL request. This call returns the newest loans at Kiva as JSON:

This call returns the same data as XML:

Simple. The format you choose probably depends on what you're most familiar with and what tools you have available to you. If you can't decide, we suggest JSON because it's concise, predictable, and all-around awesome. Some would say it is beautiful. We won't hide the fact that it is our favorite of the two. In fact, most of our data responses are designed for JSON first, then translated to XML systematically.

Because XML is by definition, extensible, it also means that saying we support XML responses doesn't provide much detail how the data might be structured. Really useful XML documents often conform to a more specific standard tied to the data they represent. In choosing our convention for XML, our first goal was to make it intuitive, and the second was to make it easily de-serializable. That is, we wanted to make the data easy to organize into an in-memory data structure such as a PHP array or a hash in Ruby. The JSON format already has this property so we created a few rules to help translate hierarchical data into XML reliably.

• Data responses are made up of ordered arrays, associative arrays (hashes), and strings.
• The root of the data response is always an associative array.
• Associative arrays are composed of keys and values. Keys translate to XML elements where the name of the key is the name of the element. The value of the element can be a string or another element depending on value type.
• Associative arrays themselves are elements with keys as child elements. The array takes its name from the respective key from the parent array. The root array always takes the name response.
• Ordered arrays also translate to named elements, but their child elements are different. The children take their name from the singular version of the parent (eg, “loans” becomes “loan”). Also, the parent element representing the array has an attribute type with the value of “list.”

As an example, here's a simplified API response in JSON:

And here's how this same data translates to XML:

Test Responses

We haven't told the full story yet. Actually, we've baked in a very special response format to every API call that we think will be really helpful for testing the Kiva API or debugging programs built on the API. Since our API is RESTful, it is trivial to call from a web browser, but JSON and XML are designed for computers to read, not humans. We thought it would be handy to provide an HTML response format that makes it easy for humans to play around with the API using any common browser. To try this out, click on this link:

http://api.kivaws.org/v1/loans/newest.html

Viola! We simply subbed out our old response extension for an HTML extension. In fact, this also works if you don't provide an extension at all. Compare this to what happens in your browser if try to request a JSON response instead.

Responses as Feeds

Some API calls can also return responses formatted as a syndicated feed, such as RSS. These are really useful with many consumer tools which have powerful built-in capabilities for tracking, presenting, and mashing up feeds. Since working with feeds can be very different than working with standard API responses, feeds have their own section. Just note that if you request a feed format for an API method which doesn't support it, you'll get an error.