Media Types - Overview

This page provides an overview of the media types of the Kenai.com APIs, as well as reference information on:

Common Fields
Root Media Type
Status Media Type

The remaining media types are documented at:

Overview

Media types indicate which entity bodies are used for requests and responses in the API. For more information on usage of media types in HTTP, see Section 3.7 of RFC 2616, HTTP/1.1.

The media types will be indicated on each response by the Content-Type header. It is recommended (though not required at this time) that when you include an entity body in a request to the API, you use the appropriate media type in the request Content-Type header as well.

All media types currently use JSON, as indicated by the +json at the end of each type name.

Common Fields

The following fields show up repeatedly in many of the entity bodies, so we'll describe them once here:

Field	Description
`content_type`	The value of the `Content-Type` header. We keep a copy in the entity body for emphasis, as a reminder of the custom types that are returned by the API.
`created_at`	Many resources have a created at date. This is an ISO8601 timestamp representing the time the resources was created.
`updated_at`	Many resources have an updated at date. This is an ISO8601 timestamp representing the most recent time the resource was changed.
`href`	The URL you are currently fetching.
`prev`	For paginated lists, if not null, a link to the previous page in the list.
`next`	For paginated lists, if not null, a link to the next page in the list.
`total`	For paginated lists, the total number of items in the list.

Root

application/vnd.com.kenai+json

The single "root" media type is what you get when requesting the topmost API resource, usually http://kenai.com/api/. It's used as a top level registry of all available resources in the API. It currently returns:

$ curl -s http://kenai.com/api.json?pretty=true
{
  "projects_href": "http:\/\/kenai.com\/api\/projects",
  "services_href": "http:\/\/kenai.com\/api\/services",
  "licenses_href": "http:\/\/kenai.com\/api\/licenses",
  "content_type": "application\/vnd.com.kenai+json"
}

Field	Description
`projects_href`	Link to the Projects collection resource
`services_href`	Link to the Services collection resource
`licenses_href`	Link to the Licenses collection resource

Status

application/vnd.com.kenai.status+json

The "status" media type is what is returned for any error response (4xx and 5xx error codes). For example, requesting a non-existent project returns:

$ curl -s http://kenai.com/api/projects/notfound.json?pretty=true
{
  "status": "404 Not Found",
  "message": "project notfound not found"
  "content_type": "application\/vnd.com.kenai.status+json",
}

If you're updating data through the APIs, a 422 response will give error messages for posted data that failed validation. For example:

$ curl -s -d '' http://kenai.com/api/projects.json?pretty=true
{
  "status": "422 Unprocessable Entity",
  "errors": {
    "description": "Description is too short (minimum is 0 characters)",
    "name": "Name has already been taken",
    "display_name": "Display name is too short (minimum is 2 characters)",
    "base": "You must login in order to create a project."
  }
  "content_type": "application\/vnd.com.kenai.status+json",
}

Field	Description
`status`	The status line as returned in the HTTP response.
`message`	An indication of why the error occurred.
`errors`	A hash of whose keys are field names that failed validation, and whose values explain why the field was invalid.