API Conventions

Parameters

In a RESTful API, parameters are a bit of a misnomer since the focus is usually on the unique URI you send with your HTTP request. Still, most developers think in terms of functional API calls so we think it helps to talk a bit about what parameters look like in our system.

The most important distinction is between required and optional parameters. You can't make an API request without a required parameter, and there is no such thing as a default value for something that's required. Because they are so essential and distinctive, required parameters always tend to pop up in the middle of our API URIs rather than somewhere at the end (i.e., the query string). For example, check out this call for detail about a loan:

http://api.kivaws.org/v1/loan/76950.xml

This request looks like a simple URL, but we call this API method loan/<id> because the value 76950 is actually a required parameter. If you changed the value to 76961 it is intuitive that you'd get data back for a different loan, which is part of the beauty of the API being RESTful.

Optional parameters usually come in the query string of the HTTP request. Sometimes they have default values too. Check out these API calls:

http://api.kivaws.org/v1/search.json http://api.kivaws.org/v1/search.json?page=1

These two calls return the same data because page is an optional parameter that has a default value of 1. Since it is passed in the query string and not a part of the main URI, it's also pretty intuitive that you don't need it for a call.

All parameters to Kiva API calls are validated. We do this mainly to protect you from making mistakes. We'd hate it if you felt responsible for accidentally screwing things up here at Kiva, but more importantly we want to give you the right feedback so you know how to fix your request. When you pass bad parameter values to an API call, we'll let you know with an error response.

Any parameter might have a unique set of restrictions, but there are some common types we refer to in our documentation:

boolean
an integer value, 0 or 1
integer
an signed integer value, 0 or 1
number
any number, including signed floats
string
almost everything else
array
a comma-delimited list of any of the above

The most significant of these basic types is the array since it's able to include values of other types. Arrays are powerful in that they let you easily make requests for lots of different data, or different types of data at once. Whitespace is respected both before and after the comma delimiter when parsing values in an array. It's okay to have an array parameter with only one value (i.e., no commas), but arrays cannot contain other arrays. Here's an example of an API call that accepts an array value:

http://api.kivaws.org/v1/loans/76950,277,37541.xml

This is call is just like one of our earlier examples except that instead of fetching the data for just one loan, we can fetch the data for three.

app_id

Every method call can accommodate app_id as a parameter. This is a value that uniquely identifies your application apart from others calling the API. It is only used for tracking purposes. You're free to send any valid value you wish.

If sent, an App ID must be a string in reverse-DNS notation at least 8 characters in length. Only alphanumeric characters, dashes, and dots are allowed. (A-Z a-z 0-9 '.' '-') Unicode and high-ASCII characters are not recommended as they are not reliably supported in URIs. If you send an invalid App ID in your API request, you may receive an error response.

We suggest you use a reversed-DNS prefix you own (like org.kiva) to ensure uniqueness of your ID. Using someone else's App ID is pointless, other than inflating someone else's statistics. We don't use App IDs for rate-limiting or security. Examples of App IDs in the suggested format include:

org.kiva.build com.foo.myGreatApplication

In addition to including app_id in API calls, you can use them in referral links to the Kiva website. This helps us track which applications are sending traffic to Kiva and driving other actions, like lending or joining teams. Check out some examples here

Kiva
  • © 2009 - 2014 Kiva. All rights reserved.
  • Terms Of Service
  • Kiva is a 501(c)(3) nonprofit.