GuidesAPI Reference
Guides

Getting Started

This page will help you get started with the Access Charity Websites API. You'll be up and running in a jiffy!

Suggest Edits

OpenAPI/Swagger Documents

You can find all of our specs here: https://developer.joyful.org/openapi/

Authentication

Our API is secured with OAuth 2.0/OpenId Connect and is currently configured for server-to-server communications.

You will need to request a ClientId and ClientSecret from your customer success manager in order to gain access to the API.

When communicating with the API you will need to provide a bearer token in the form of a JWT. In order to get a JWT, you will need contact our Identity Server to generate an access token for your credentials using the client_credentials grant type.

📘

OAuth Scope

When communicating with our OAuth server, you will need to explicitly request permission to access the API. You can do this by providing the scope platformapiaccess.

var oauthClient = new OAuthClient("https://app.altruisticidentity.com");
var discoveryDocument = oauthClient.GetDiscoveryDocument();

var accessToken = oauthClient.RequestAccessToken(new {
  TokenEndpoint = discoveryDocument.TokenEndpoint,
  ClientId = "fetch-from-config",
  ClientSecret = "fetch-from-config",
  Scope = "platformapiaccess",
  GrantType = "client_credentials"
});

curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" https://api.joyful.org/someresource

Useful Links:

Rate limiting

For API requests, you can make up to 60 requests per minute. You will be notified of hitting this limit with the HTTP status 429: Too Many Requests.

Platforms

Joyful is built upon a multi-tenanted architecture and the API reflects this. In order to use the API, most endpoints will require you to provide a platformId.

Use the list platforms endpoint to find platforms you have permission to access.

Traversing with Pagination

Basics of Pagination

To start with, it's important to know a few facts about receiving paginated items:

  • You can specify how many items to receive (up to a maximum of 50)
  • Not all list endpoints will have the same default number of items being returned
  • Information about pagination is provided in the Link header of an API call
  • Paging always starts at 1

📘

HTTP Headers

Following HTTP standards, Headers are not case sensitive. Please make sure you keep that in mind when writing custom integrations.

Link Headers

If we were to request to list all members, we are returned the following header value for Link:

<https://api.joyful.org/platforms/{platformId}/members/?page=2>; rel="next"

Let's break that down. rel="next" says that the next page is page=2. This makes sense, since by default, all paginated queries start at page 1.

If we follow this link, we are returned the following link header:

<https://api.joyful.org/platforms/{platformId}/members/?page=1>; rel="prev", <https://api.joyful.org/platforms/{platformId}/members/?page=3>; rel="next"

Let's break that down. rel="next" says that the next page is page=3. This makes sense as we are now on page 2 page=2. rel="prev" provides some more information, stating that the previous page is page 1.

Always rely on these link relations provided to you. Don't try to guess or construct your own URL.

Total number of resources

Additional meta-data is returned as part of a paging query to represent the number of resources found for that request.

The response HTTP header Total-Resource-Count contains this total, and can be useful e.g. used to display in the UI.

String Properties

All string properties returned from all of our endpoints will default to null if they are empty or whitespaces. So for these properties you'll only ever get the value of the string or null.

Patch Verb

We use Json-Patch via the PATCH HTTP verb to enable updating a resource. For further information on a Json-Patch, please read here: http://jsonpatch.com.

We currently only support the replace operation, which allows you to change a value of a property on a given resource. If any other operations or invalid property names are provided, these will be treated as a BadRequest.

As an example you can use the following to update the platform Title:

[
    { "op" : "replace", "path": "Title", "value": "New platform title" }
}

You can also replace the value of a whole object, for example you could update the whole of the platform Culture like so:

[
    { 
        "op" : "replace",
        "path": "culture",
        "value": 
        { 
            "timezone": "Europe/London",
            "country": "GBR", 
            "currency" : "GBP", 
            "taxRate": 20,
            "taxLabel": "VAT"
        } 
]

Additionally, you can update a single property within the Culture object like so:

[
    { "op" : "replace", "path": "Culture/Country", "value": "IRE" }
}

Not all resources support PATCH - please refer to the API documentation for details on what resources support PATCH.

Updated 5 months ago