Learn how to navigate the resources provided by the Giveabl REST API.
Giveabl's APIs (Application Programming Interfaces) power its donation platform. Behind these APIs is a software layer connecting charities, NPOs and social enterprises, along with Charitable Funds and Foundations, to facilitate automated donations globally.
What is an API?
API is short for 'Application Programming Interface'. It is a set of rules that allow computer programs to communicate with each other. An API defines the way the program will communicate, what data will be exchanged, and how the data will be formatted.
All Giveabl REST API access is over HTTPS, and accessed from:
https://api.giveabl.com
The API is organized around REST.
REST stands for 'Representational State Transfer'. Web services that conform to the REST architectural pattern are generally APIs that are accessed using the HTTP protocol at a predefined set of URLs.
These URLs represent various resource objects, typically returned as JSON. Often, resources have methods that can be performed over HTTP, like GET, POST, PATCH and DELETE. Giveabl's API uses POST to create new resource objects, and PATCH to update existing resource objects.
Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
HTTP verbs
Where possible, the Giveabl REST API strives to use appropriate HTTP verbs for each action.
| Verb | Description |
|---|---|
| GET | Used for retrieving resources. |
| POST | Used for creating resources. |
| PATCH | Used for updating resources with partial JSON data. For instance, an Fundraiser resource has title and excerpt attributes. A PATCH request may accept one or more of the attributes to update the resource. |
| PUT | Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero. |
| DELETE | Used for deleting resources. |
Standard URL structures
Create a :resource
POST /v1/:resources
Retrieve a :resource
GET /v1/:resources/:resource_id
Retrieve all :resources
GET /v1/:resources
Update a :resource
PATCH /v1/:resources/:resource_id
:action a :resource
PATCH /v1/:resources/:resource_id/:action
Delete a :resource
DELETE /v1/:resources/:resource_id
Standard responses
Responses are returned in a consistent, standard format that includes a data property and a meta property.
Single result
Returning a single result (object):
{
// ...
}
List of results
Returning a list of results (data is an array of objects, meta includes pagination):
{
"data": [
{
// ...
},
{
// ...
},
// ...
],
"meta": {
"pagination": {
"page": 1,
"page_size": 25,
"total": 56,
"page_count": 3
}
}
}
Test mode
You can use the Giveabl API in test mode, which does not affect your live data or interact with payment processing networks. The API Key you use to authenticate the request determines whether the request is live mode or test mode.