needish

Needish API

Needish exposes some of its functionality via an API (Application programming interface). This document serves as reference for developers wanting to write fun applications that interact with Needish.

API Discussion Group

A Google Group has been created to discuss Needish API related topics. To keep updated with the API development, and discuss API related topics, suscribe to http://groups.google.com/group/needish-api

Creating Applications

Before creating your application using the Needish API, you must obtain a valid application key. The key will be used to track API usage.

Currently, commercial use of the API is allowed only with prior permission. Requests for API keys intended for commercial use are reviewed by Needish. If your project is personal, artistic, free or otherwise non-commercial please don't request a commercial key. If your project is commercial, please provide sufficient detail to help us decide.

If you want to create an application, obtain your application key here

User Authentication

Most API methods require authentication as in the Needish website. But there are some open functionalities, for example requesting the list of last posted needs.

The only supported authentication scheme at this time is Basic HTTP authentication using the email registered at Needish and the password chosen.

Encoding

The needish API expects all parameters to be UTF-8 encoded. If you need more information about UTF-8. Additionaly remember to URL encode parameters that take complex strings.

Request

The Needish API is built based on the REST (Representational State Transfer) software architecture style. Methods can return data using the XML or JSON data formats.

To retrieve the last posted needs in the XML data format you should use (replace <your_api_key> with your own API key)

http://api.needish.com/needs/all.xml?api_key=<your_api_key>

If you want to user the JSON data format, you should only change the extension to .json

http://api.needish.com/needs/all.json?api_key=<your_api_key>

For JSON requests you can define your own callback function name, using the callback parameter. Example:

http://api.needish.com/needs/all.json?callback=showNeeds&api_key=<your_api_key>

returns

showNeeds({...});

All methods require a GET request, unless noted. Methods that add entities require a POST method to be used.

General Parameters

All the methods that returns lists of entities (ie: needs, users or helps), accept the following parameters:

limit
Limits the number of entities to return.
page
The page to retrieve. It's 1-base (first page is 1), but if you send 0 the first page will be returned, anyway.
since
Optional. Returns entities created after the specified date. Date should be in yyyy-mm-dd format or using UNIX time (number of seconds elapsed since 1970-01-01 00:00:00)

Responses

If the response is OK, then the following will be returned:

XML Format

<?xml version="1.0" encoding="UTF-8" ?>
<rsp>
	[response-here]
</rsp>

JSON Format

{
	"rsp": {
		[response-here]
	}
}

Also, an "Status-Code: 200" header will be sent

If the response fails, or nothing can be returned (example: no user found):

XML Format

<?xml version="1.0" encoding="UTF-8" ?>
<rsp>
	<status code="[code]" msg="[message]"/>
	<errors>
		<error field="[fieldname]" message="[message]" />
	</error>
</rsp>

JSON Format

{
	"rsp": {
		"status":{
			"code":"[code]",
			"msg":"[message]"
		},
		"errors":[
			{
				field:"[fieldname]",
				message:"[message]"
			}
		]
	}
}

Also, an "Status-Code: [code]" header will be sent.

Response Status Code

200
OK
401
Unauthorized. Returned when trying to execute an authenticated method without valid credentials.
405
Method not allowed. Returned when trying to execute with a wrong method (Example: using GET when you should be using POST)
404
Not Found. No method, or no data found.
500
API Error. There was an error when executing a method. The message field contains details of the error.