Rest-API
The FundraisingBox REST API is implemented as vanilla XML over HTTPS.
Every resource, like Donation, Person, or Project, has their own URL and are manipulated in isolation. In other words, we’ve tried to make the API follow the REST principles as much as we can.
You can explore the view part of the API (everything that’s fetched with GET) through a regular browser. Using Firefox for this is particularly nice as it has a good, simple XML renderer (unlike Safari which just strips the tags and dumps the content). Pretty much any URL in the FundraisingBox can be viewed in its XML form by adding the .xml extension. So /persons/4 becomes /persons/4.xml if you want to see the XML version.
This API is deprecated
Please use the new JSON-API!
Authentication
When you’re using the API, it’s always through an existing user in your FundraisingBox. There’s no special API user. Authenticating is done with an authentication token. Please contact our support team to retrieve your token.
When using the authentication token, you don’t need a separate password. But since FundraisingBox uses HTTP Basic Authentication, and lots of implementations assume that you want to have a password, it’s often easier just to pass in a dummy password, like X.
Example using the authentication token and a dummy password through curl:
curl -u 605b32dd:X https://api.fundraisingbox.com/persons/1.xml
Remember that anyone who has your authentication token can see and change everything you have access to. So you want to guard that as well as you guard your username and password. If you come to fear that it has been compromised, you can regenerate it at any time. Just open a ticket.
Reading through the API
The FundraisingBox API has two category of actions for reading: Show and list. Show returns a single record and list returns a collection. There’s usually just a single show action for each resource, but many lists. All these actions are done through GET, which also means that they’re all easily explorable through a browser as described above.
A few examples of reading with curl:
curl -u 605b32dd:X https://api.fundraisingbox.com/persons/5.xml
curl -u 605b32dd:X https://api.fundraisingbox.com/donations/5.xml
If the read is successful, you’ll get an XML response back along with the status code „200 OK“.
Dealing with failure
If a request fails, the error information is returned with the HTTP status code. For instance, if a requested record could not be found, the HTTP response might look something like:
HTTP/1.1 404 The record could not be found
Date: Thu, 16 Mar 2016 17:41:40 GMT
...
Note that, in general, if a request causes a new record to be created (like a new message, or to-do item, etc.), the response will use the „201 Created“ status. Any other successful operation (like a successful query, delete, or update) will use a 200 status code.
SSL Note
Always use https://api.fundraisingbox.com! If you perform a request on http you will get a redirect answer in return.
Conventions in the API documentation
In the documentation that follows, the following notation is used:
{text}: Indicates text that should be replaced by your own data
...: Indicates content from the response has been elided for brevity in documentation. See the list of data responses at the end of the page for a full description of the format of that response type.