Kenai Web APIs
The easiest way to get started with the kenai.com APIs is to simply visit http://kenai.com/api. This displays the root service document from which most of the other resources are available. You can simply click through links to drill down into specific parts of the API and see what information is available from the comfort of your web browser.
Each resource or API will be described by the following template.
|Version||1.0 (versioning described below)|
|Request|| GET /api/path?params|
Content-Type: media type expected, if any
|Response|| Success: 200 OK|
Failure: 400 Bad Request Content-Type: media type, if there is any response body
Each API or resource will be versioned. Initially, for any version 1 API, no version information will need to be specified. Any use of the API will always default to version 1 if no version is specified.
The API will have major and minor revision numbers (x.y). The minor revision number will be incremented whenever a compatible change is introduced. A compatible change is limited to the following:
- The introduction of a new resource, API, or method that does not affect existing resources/APIs
- The introduction of a new field or a new value for a field whose values are enumerated.
An incompatible change is any change or removal of resource URIs, APIs, or methods, or structural modification or removal of the fields in the payload representations.
API versions will be specified in the hostname, so for example http://v1.api.kenai.com/api/.. will correspond to version 1 of the API. Version 1 will also be available without any leading version identifier in the hostname (e.g., http://kenai.com/api/...).
The main machine-readable representation provided by the API is JSON. However, the default representation is HTML with pretty-printed, linked JSON for easy exploration.
To select JSON as the return format do one of:
- append the .json suffix to the URL, e.g., http://kenai.com/api/projects becomes http://kenai.com/api/projects.json.
- Send application/json in the HTTP Accept header as part of your request. For example:
There are several common parameters that can be used in the query string to modify behavior.
These parameters are available on all actions:
- callback=function_name — JSONP will be returned with function_name(...) wrapped around the JSON.
- pretty=true — The JSON will be pretty-printed for more human-readable output.
These parameters are available on any resource list. (Resource lists are denoted by a media type string whose noun is pluralized.)
- q=keyword — Search or filter the list by the given keywords.
- page=page_number — Specify the number of the page to show.
- size=num_results — Specify the number of results per page.
Media types are the nouns of the system. They describe the structure of the data passing in and out of the APIs. Media types are indicated using the standard Content-Type header in requests and responses.
In this document, we distinguish between resource APIs and single-purpose APIs.
- Resources are modeled after the Atom Publishing Protocol Model and respond to the four HTTP verbs GET/POST/PUT/DELETE in a uniform manner.
- Single-purpose APIs are narrow methods using GET and/or POST that don't fit into a create/read/update/delete collection.
Resources and API methods will accept HTTP basic authentication to identify the user of the API. Whether or not authentication is required, optional, or unnecessary will be indicated with each resource or API.
- In the cases where authentication is required, a failed authentication will return an HTTP status 401 Unauthorized.
- In the cases where authentication is optional, a successful authentication will reveal information that wouldn't be shown to an anonymous API user. Failed authentication will still return 401 for consistency.
- Unnecessary authentication means that sending credentials will have no effect on the response.
It is recommended, though not required, to use the https/SSL version of resource and API URLs so that the credentials are not exposed on the client's local network.
Error responses will always be indicated first and foremost by the HTTP status code. In accordance with HTTP, 4xx errors are the client's fault while 5xx errors are the server's fault.
In the case of errors where a JSON format was requested (see above), the JSON returned will always use the Status media type.