This revision made August 28, 2009 20:41, by Paul

Kenai Web APIs

This page provides both a list of links to the API reference documentation and an overview of common API features and conventions used to describe the APIs. For your convenience, the API Reference Documentation is listed first, but it's useful to read through the Overview the first time you come here to get an idea of how it all works.

One way to get started with the kenai.com APIs is to go to http://kenai.com/api. This URL displays the root service document from which most of the other resources are available. You can click through links to drill down into specific parts of the API and see what information is available.

Note: All clients must use the HTTPS protocol to access these APIs.

API Reference Documentation

Overview

Template

Each resource or API description uses the following template.

Version 1.0 (versioning described below)
Authentication required|optional|unnecessary
URI /api/path/...
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

Versioning

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.

Versioning Policy

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.

Versions > 1

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/...).

Representations

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 the following:

Common Parameters

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

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.

Resources vs. APIs

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.

Service Authentication

Resources and API methods will accept HTTP basic authentication to identify the user of the API. Whether the 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.

Note: It is required that you use the HTTPS/SSL version of the resource and API URLs so the credentials aren't exposed.

Errors

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.

Difference compared to previous revision
=== Template=== Each resource or API description uses the following template. {| border="1" |- valign="top" | Version | 1.0 (versioning described below) |- valign="top" | Authentication | required|optional|unnecessary |- valign="top" | URI | /api/path/... |- valign="top" | Request | GET /api/path?params
Content-Type: media type expected, if any |- valign="top" | Response | Success: 200 OK
Failure: 400 Bad Request
  • Mysql
  • Glassfish
  • Jruby
  • Rails
  • Nblogo
Terms of Use; Privacy Policy;
© 2013, Oracle Corporation and/or its affiliates
(revision 20140418.2d69abc)
 
 
Close
loading
Please Confirm
Close