{"_id":"571f7fc8d1ebe0190017e650","parentDoc":null,"category":{"_id":"571f7fb0ac2a080e0014c661","__v":0,"project":"571f5e8cd8667f0e00a3c498","version":"571f5e8cd8667f0e00a3c49b","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-04-26T14:48:16.712Z","from_sync":false,"order":7,"slug":"rest-api","title":"REST-API"},"version":{"_id":"571f5e8cd8667f0e00a3c49b","hasDoc":true,"__v":12,"hasReference":true,"project":"571f5e8cd8667f0e00a3c498","createdAt":"2016-04-26T12:26:52.312Z","releaseDate":"2016-04-26T12:26:52.312Z","categories":["571f5e8cd8667f0e00a3c49c","571f73cfcb4baa0e00d13a80","571f7451cb4baa0e00d13a88","571f7d2720695f3400f38797","571f7fb0ac2a080e0014c661","571f884be54f2d0e003ebb0a","572200c9ecb38d0e00d80ebd","572c301e7c8eff0e00aaa174","57df91b2c6348d0e0020c452","57e104db9ff1e21900a721ab","57fd04caeaa77f19008b8202","5899c7113514ce0f0014da84"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":7,"user":"571f5e46d8e3cf1900762b33","project":"571f5e8cd8667f0e00a3c498","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-26T14:48:40.176Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":0,"body":"The FundraisingBox REST API is implemented as vanilla XML over HTTPS.\nEvery 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.\n\nYou 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. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nWhen 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, which receive from the Support Team (Just use the top right contact button to open a support ticket).\n\nWhen 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.\n\nExample using the authentication token and a dummy password through curl:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -u 605b32dd:X https://secure.fundraisingbox.com/persons/1.xml\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nRemember 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Reading through the API\"\n}\n[/block]\nThe 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.\n\nA few examples of reading with curl:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -u 605b32dd:X https://secure.fundraisingbox.com/persons/5.xml\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -u 605b32dd:X https://secure.fundraisingbox.com/donations/5.xml\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIf the read is successful, you’ll get an XML response back along with the status code „200 OK“.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Dealing with failure\"\n}\n[/block]\nIf 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: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/1.1 404 The record could not be found\\nDate: Thu, 16 Mar 2016 17:41:40 GMT\\n...\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nNote 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.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Always use [https://secure.fundraisingbox.com](https://secure.fundraisingbox.com)! If you perform a request on http you will get a redirect answer in return.\",\n  \"title\": \"SSL Note\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Conventions in the API documentation\"\n}\n[/block]\nIn the documentation that follows, the following notation is used:\n\n    {text}: Indicates text that should be replaced by your own data\n    \n    ...: 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.","excerpt":"Rest-API","slug":"rest-api","type":"basic","title":"Introduction"}

Introduction

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. [block:api-header] { "type": "basic", "title": "Authentication" } [/block] 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, which receive from the Support Team (Just use the top right contact button to open a support ticket). 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: [block:code] { "codes": [ { "code": "curl -u 605b32dd:X https://secure.fundraisingbox.com/persons/1.xml", "language": "text" } ] } [/block] 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. [block:api-header] { "type": "basic", "title": "Reading through the API" } [/block] 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: [block:code] { "codes": [ { "code": "curl -u 605b32dd:X https://secure.fundraisingbox.com/persons/5.xml", "language": "text" } ] } [/block] [block:code] { "codes": [ { "code": "curl -u 605b32dd:X https://secure.fundraisingbox.com/donations/5.xml", "language": "text" } ] } [/block] If the read is successful, you’ll get an XML response back along with the status code „200 OK“. [block:api-header] { "type": "basic", "title": "Dealing with failure" } [/block] 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: [block:code] { "codes": [ { "code": "HTTP/1.1 404 The record could not be found\nDate: Thu, 16 Mar 2016 17:41:40 GMT\n...", "language": "text" } ] } [/block] 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. [block:callout] { "type": "warning", "body": "Always use [https://secure.fundraisingbox.com](https://secure.fundraisingbox.com)! If you perform a request on http you will get a redirect answer in return.", "title": "SSL Note" } [/block] [block:api-header] { "type": "basic", "title": "Conventions in the API documentation" } [/block] 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.