This revision made July 24, 2009 15:58, by Nick Sieger

Kenai Web APIs


Introduction


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.

Template

Each resource or API will be described by 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/...).

Representation

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:

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_nameJSONP 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 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.

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.

API Contents

Difference compared to previous revision
Each resource or API will be described by the following template. {| border="1" |- | Status | proposed|accepted|deployed (date, revision) |- | Version | 1.0 (versioning described below) |- | Authentication
  • Mysql
  • Glassfish
  • Jruby
  • Rails
  • Nblogo
Terms of Use; Privacy Policy;
© 2013, Oracle Corporation and/or its affiliates
(revision 20131025.e7cbc9d)
 
 
Close
loading
Please Confirm
Close