Needish

API Discussion Group

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.

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.

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:

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

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

returns

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.