DRAFT - API not released yet

API reference

The BeWelcome API implements REST via HTTP, using methods GET, POST, PUT and DELETE. Authentication is done via simple session authentication token. Currently only JSON as output format is supported.

Making requests

URI pattern:

https://www.bewelcome.org/api/v1/{resource_path}.{format}?{parameters}

For example, to retrieve a public member profile, type this in a command line:

curl https://www.bewelcome.org/api/v1/members/casey.json?key=aabbccdd

API keys

To monitor usage of our API and to prevent abuse, access is restricted by a key tied to your user profile. Generate your key by logging in to BeWelcome and filling in the API key form.

Authentication

Authentication is done via simple token exchange. Retrieve an authentication token by using the sessions resource documented below and send it as URL parameter authToken with each request that requires authentication.

Resources

Different HTTP methods are used to operate on collections and specific elements of the same resource. Generally POST on a collection (e.g. sessions) creates a new element and PUT on an element (e.g. members/karl) updates the element. GET and DELETE on elements will do precisely that - retrieve or remove. Resources in detail:

Create new session (log in)

POST sessions

Required data:

{
  "username" : "{username}",
  "password" : "{password}"
}

Example:

curl -X POST https://www.bewelcome.org/api/v1/sessions.json?key=aabbccdd -d '{"username":"casey","password":"nonprofit"}'

Example response:

HTTP/1.1 201 Created
{
  "status" : "success",
  "session" : {
    "created" : "2013-01-29 13:56:51",
    "authToken" : "e2eb13834ef70726a7fea6dc3e52e540",
    "inactivityTimeout" : "2013-01-29 15:13:02",
    "expires" : "2013-01-30 13:56:51"
  }
}

Read session information

GET sessions/{identifier}

Use authToken as identifier. Apart from returning session information this will also refresh the session by extending its inactivity timeout.

Example:

curl https://www.bewelcome.org/api/v1/sessions/e2eb13834ef70726a7fea6dc3e52e540.json?key=aabbccdd

Example response:

HTTP/1.1 200 OK
{
  "status" : "success",
  "session" : {
    "created" : "2013-01-29 13:56:51",
    "authToken" : "e2eb13834ef70726a7fea6dc3e52e540",
    "inactivityTimeout" : "2013-01-29 15:13:02",
    "expires" : "2013-01-30 13:56:51"
  }
}

Delete a session (log out)

DELETE sessions/{identifier}

Use authToken as identifier.

Example:

curl -X DELETE https://www.bewelcome.org/api/v1/sessions/e2eb13834ef70726a7fea6dc3e52e540.json?key=aabbccdd

Example response:

HTTP/1.1 200 OK
{
  "status" : "success"
}

Read member information

GET members/{username}

URL parameters:

Example (no authentication):

curl https://www.bewelcome.org/api/v1/members/casey.json?key=aabbccdd

Example response:

HTTP/1.1 200 OK
{
  "status" : "success",
  "member" : { ... }
}

Example (with authentication and forUpdate):

curl "https://www.bewelcome.org/api/v1/members/casey.json?key=aabbccdd&authToken=e2eb13834ef70726a7fea6dc3e52e540&forUpdate=1"

Example response:

HTTP/1.1 200 OK
{
  "status" : "success",
  "member" : { ... }
}

Update member information

PUT members/{username}

As data all writable fields can be sent. See forUpdate parameter at GET members for a list of writable fields. Fields can be omitted, but to make sure all field dependencies are met always send all fields.

Example:

curl -X PUT "https://www.bewelcome.org/api/v1/members/casey.json?key=aabbccdd&authToken=e2eb13834ef70726a7fea6dc3e52e540" -d '{"occupation":"Philantropist"}'

Example response:

HTTP/1.1 200 OK
{
  "status" : "success"
}

Errors

Usually requests will return status success, but if an error occured status error or server error along with an error code and an error message will be sent. Low-level errors will be sent without a format as a plain text response. In addition to these errors the HTTP response status code will give further clues.

Low level error example:

curl -i https://www.bewelcome.org/api/v1/members/karl.xml

HTTP/1.1 400 Bad Request
Format "xml" not supported (errorCode: 4003)

JSON error example:

curl -i https://www.bewelcome.org/api/v1/members/unknown.json?key=aabbccdd

HTTP/1.1 404 Not Found
{
  "status" : "error",
  "errorCode" : 4010,
  "errorMessage" : "Member not found"
}

Error codes

Codes in the 4000 range indicate an invalid request to the API. If a code in the 5000 range occurs, something went wrong on the server and this should only be temporary. If server errors persist, please notify us.

Currently implemented error codes: