2009-04-01T17:54:51Z

Added in top-level link for members resource 1203 Home 31

<h1>Kenai Web APIs</h1> 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 <a href="{{project kenaiapis page MediaTypes}}#application/vnd.com.kenai.root+json">root service document</a> 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. <h2> API Reference Documentation </h2> * [[Media Types]] *[[ProjectsAPI|Project Resource]] *[[AuthAPI|Authentication and Authorization API]] *[[WikiAPI|Wiki Resource]] *[[ForumsAPI|Forum Resource]] *[[LicensesAPI|License Resource]] *[[ServicesAPI|Service Resource]] *[[MembersAPI | Member Resource]] <h2>Overview </h2> __TOC__ === 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 | <tt>/api/path/...</tt> |- valign="top" | Request | GET /api/path?params<br/> Content-Type: media type expected, if any |- valign="top" | Response | Success: 200 OK<br/> 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 <tt><nowiki>http://v1.api.kenai.com/api/..</nowiki></tt> will correspond to version 1 of the API. Version 1 will also be available without any leading version identifier in the hostname (e.g., <tt><nowiki>http://kenai.com/api/...</nowiki></tt>). === Representations=== The main machine-readable representation provided by the API is [http://www.json.org/ 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: * Append the <tt>.json</tt> suffix to the URL. For example, <tt>[https://kenai.com/api/projects]</tt> becomes <tt>[https://kenai.com/api/projects.json]</tt>. * Send <tt>application/json</tt> in the HTTP Accept header as part of your request. For example:<br/><br/><tt>   Accept: application/json</tt> === 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: * <tt>callback=function_name</tt> - [http://en.wikipedia.org/wiki/JSON#JSONP JSONP] will be returned with <tt>function_name(...)</tt> wrapped around the JSON. * <tt>pretty=true</tt> - 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.) * <tt>q=keyword</tt> - Search or filter the list by the given keywords. * <tt>page=page_number</tt> - Specify the number of the page to show. * <tt>size=num_results</tt> - 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 <tt>Content-Type</tt> header in requests and responses. === Resources vs. APIs=== In this document, we distinguish between resource APIs and single-purpose APIs. *Resources are modeled after [http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-04.html#rfc.section.4 the Atom Publishing Protocol Model] and respond to the four HTTP verbs <tt>GET/POST/PUT/DELETE</tt> in a uniform manner. *Single-purpose APIs are narrow methods using <tt>GET</tt> and/or <tt>POST</tt> 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 <tt>401 Unauthorized</tt>. * 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 <a href="{{project kenaiapis page MediaTypes}}#application/vnd.com.kenai.status+json">Status</a> media type.

<p><h1>Kenai Web APIs</h1> 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. </p><p>One way to get started with the kenai.com APIs is to go to <a class='external' href="http://kenai.com/api">http://kenai.com/api</a>. This URL displays the <a href="<?url_for_resource project kenaiapis page MediaTypes?>#application/vnd.com.kenai.root+json">root service document</a> 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. </p><p><b>Note:</b> All clients must use the HTTPS protocol to access these APIs. </p><p><h2> API Reference Documentation </h2></p><ul><li> <a href='<?url_for_page Media Types?>' class='<?class_for_page_link Media Types?>'>Media Types</a></li><li><a href='<?url_for_page ProjectsAPI?>' class='<?class_for_page_link ProjectsAPI?>'>Project Resource</a></li><li><a href='<?url_for_page AuthAPI?>' class='<?class_for_page_link AuthAPI?>'>Authentication and Authorization API</a></li><li><a href='<?url_for_page WikiAPI?>' class='<?class_for_page_link WikiAPI?>'>Wiki Resource</a></li><li><a href='<?url_for_page ForumsAPI?>' class='<?class_for_page_link ForumsAPI?>'>Forum Resource</a></li><li><a href='<?url_for_page LicensesAPI?>' class='<?class_for_page_link LicensesAPI?>'>License Resource</a></li><li><a href='<?url_for_page ServicesAPI?>' class='<?class_for_page_link ServicesAPI?>'>Service Resource</a></li><li><a href='<?url_for_page MembersAPI ?>' class='<?class_for_page_link MembersAPI ?>'> Member Resource</a></li></ul><p><h2>Overview </h2></p><div id='toc' class='toc'> <div id='toctitle' class='toc-title'> <span>Contents</span> </div> <div id='toccontents' class='toc-contents'><ul><ul><ul><li>1 <a href='#Template'> Template</a></li> <li>2 <a href='#Versioning'> Versioning</a></li> <ul><li>2.1 <a href='#Versioning_Policy'> Versioning Policy</a></li> <li>2.2 <a href='#Versions_>_1'> Versions > 1</a></li> </ul><li>3 <a href='#Representations'> Representations</a></li> <li>4 <a href='#Common_Parameters'> Common Parameters</a></li> <li>5 <a href='#Media_Types'> Media Types</a></li> <li>6 <a href='#Resources_vs._APIs'> Resources vs. APIs</a></li> <li>7 <a href='#Service_Authentication'> Service Authentication</a></li> <li>8 <a href='#Errors'> Errors</a></li> </ul></ul></ul></div> </div><h3><a name='Template'></a> Template</h3> <p>Each resource or API description uses the following template. </p><div style="overflow-x: auto;"><div style="margin: 0px 2px 0px 2px;"> <table border="1"><tr valign="top"><td> Version </td><td> 1.0 (versioning described below) </td></tr> <tr valign="top"><td> Authentication </td><td> required|optional|unnecessary </td></tr> <tr valign="top"><td> URI </td><td> <tt>/api/path/...</tt></td></tr> <tr valign="top"><td> Request </td><td> GET /api/path?params<br /> Content-Type: media type expected, if any </td></tr> <tr valign="top"><td> Response </td><td> Success: 200 OK<br /> Failure: 400 Bad Request Content-Type: media type, if there is any response body </td></tr> </table> </div></div> <h3><a name='Versioning'></a> Versioning</h3> <p>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. </p><h4><a name='Versioning_Policy'></a> Versioning Policy</h4> <p>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: </p><ul><li> The introduction of a new resource, API, or method that does not affect existing resources/APIs </li><li> The introduction of a new field or a new value for a field whose values are enumerated. </li></ul><p> 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. </p><h4><a name='Versions_>_1'></a> Versions > 1</h4> <p>API versions will be specified in the hostname, so for example <tt>http://v1.api.kenai.com/api/..</tt> will correspond to version 1 of the API. Version 1 will also be available without any leading version identifier in the hostname (e.g., <tt>http://kenai.com/api/...</tt>). </p><h3><a name='Representations'></a> Representations</h3> <p>The main machine-readable representation provided by the API is <a class='external' href="http://www.json.org/">JSON</a>. However, the default representation is HTML with pretty-printed, linked JSON for easy exploration. </p><p>To select JSON as the return format do one of the following: </p><ul><li> Append the <tt>.json</tt> suffix to the URL. For example, <tt><a class='external' href="https://kenai.com/api/projects">https://kenai.com/api/projects</a></tt> becomes <tt><a class='external' href="https://kenai.com/api/projects.json">https://kenai.com/api/projects.json</a></tt>. </li><li> Send <tt>application/json</tt> in the HTTP Accept header as part of your request. For example:<br /><br /><tt>   Accept: application/json</tt></li></ul><h3><a name='Common_Parameters'></a> Common Parameters</h3> <p>There are several common parameters that can be used in the query string to modify behavior. </p><p>These parameters are available on all actions: </p><ul><li> <tt>callback=function_name</tt> - <a class='external' href="http://en.wikipedia.org/wiki/JSON#JSONP">JSONP</a> will be returned with <tt>function_name(...)</tt> wrapped around the JSON. </li><li> <tt>pretty=true</tt> - The JSON will be pretty-printed for more human-readable output. </li></ul><p> These parameters are available on any resource list. (Resource lists are denoted by a media type string whose noun is pluralized.) </p><ul><li> <tt>q=keyword</tt> - Search or filter the list by the given keywords. </li><li> <tt>page=page_number</tt> - Specify the number of the page to show. </li><li> <tt>size=num_results</tt> - Specify the number of results per page. </li></ul><h3><a name='Media_Types'></a> Media Types</h3> <p><a href='<?url_for_page Media types?>' class='<?class_for_page_link Media types?>'>Media types</a> 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 <tt>Content-Type</tt> header in requests and responses. </p><h3><a name='Resources_vs._APIs'></a> Resources vs. APIs</h3> <p>In this document, we distinguish between resource APIs and single-purpose APIs. </p><ul><li>Resources are modeled after <a class='external' href="http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-04.html#rfc.section.4">the Atom Publishing Protocol Model</a> and respond to the four HTTP verbs <tt>GET/POST/PUT/DELETE</tt> in a uniform manner. </li><li>Single-purpose APIs are narrow methods using <tt>GET</tt> and/or <tt>POST</tt> that don't fit into a create/read/update/delete collection. </li></ul><h3><a name='Service_Authentication'></a> Service Authentication</h3> <p>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. </p><ul><li> In the cases where authentication is required, a failed authentication will return an HTTP status <tt>401 Unauthorized</tt>. </li><li> 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. </li><li> Unnecessary authentication means that sending credentials will have no effect on the response. </li></ul><p><b>Note:</b> It is required that you use the HTTPS/SSL version of the resource and API URLs so the credentials aren't exposed. </p><h3><a name='Errors'></a> Errors</h3> <p>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. </p><p>In the case of errors where a JSON format was requested (see above), the JSON returned will always use the <a href="<?url_for_resource project kenaiapis page MediaTypes?>#application/vnd.com.kenai.status+json">Status</a> media type. </p>

2010-01-13T08:00:06Z

4686