Feature: add new routes for donations and donors

[glaubersilva]

Related to GIVE-1392 and GIVE-1393

Description

This PR implements 4 new REST API endpoints to retrieve Donations and Donors. In the endpoints that return multiple entries, is possible to filter the returned data using custom parameters in the request and also is possible use pagination and sort the results using the page, per_page, sort and direction parameters.

Another thing to consider is that sensitive data will be returned only if the user making the request is the site administrator.

Sensitive data for donations:

$sensitiveProperties = [
    'donorIp',
    'email',
    'phone',
    'billingAddress',
];

Sensitive data for donors:

$sensitiveProperties = [
    'userId',
    'email',
    'phone',
    'additionalEmails',
];

The new endpoints to retrieve a single entry:

/give-api/v2/donations/(?P<id>[0-9]+)

/give-api/v2/donors/(?P<id>[0-9]+)

The new endpoints to retrieve multiple entries:

/give-api/v2/donations

/give-api/v2/donors

Important: These endpoints that return multiple entries allow filtering the returned data through the campaignId parameter. It's also possible to use the hideAnonymousDonations or hideAnonymousDonors parameter to exclude from the results the donations/donors that made anonymous donations. Beyond that, on the /give-api/v2/donors endpoint, it is possible to use the onlyWithDonations parameter to retrieve all donors or just the ones that have valid donations completed.

Sample request including anonymous donations in the results:

$request = new WP_REST_Request('GET' 'give-api/v2/donations');

$request->set_query_params(
    [
        'hideAnonymousDonations' => false,   
        //'campaignId' => $campaign1->id, //Uncomment this line to filter by campaign
    ]
);

Sample request including anonymous donors in the results:

$request = new WP_REST_Request('GET' 'give-api/v2/donors');

$request->set_query_params(
    [
        'hideAnonymousDonors' => false,   
        //'campaignId' => $campaign1->id, //Uncomment this line to filter by campaign
    ]
);

Sample request to retrieve the 5 most recent donations:

$request = new WP_REST_Request('GET' 'give-api/v2/donations');

$request->set_query_params(
    [
        'page' => 1,
        'per_page' => 5,
        'sort' => 'createdAt',
        'direction' => 'DESC',
        //'campaignId' => $campaign1->id, //Uncomment this line to filter by campaign
    ]
);

Sample request to retrieve the top 5 donors:

$request = new WP_REST_Request('GET' 'give-api/v2/donors');

$request->set_query_params(
    [
        'page' => 1,
        'per_page' => 5,
        'sort' => 'totalAmountDonated',
        'direction' => 'DESC',
        //'campaignId' => $campaign1->id, // Uncomment this line to filter by campaign
    ]
);

Affects

GiveWP Rest API endpoints available for public use.

Testing Instructions

In your terminal, run the following commands:

composer test -- --filter GetDonationRouteTest

composer test -- --filter GetDonationsRouteTest

composer test -- --filter GetDonorRouteTest

composer test -- --filter GetDonorsRouteTest

Pre-review Checklist

• Acceptance criteria satisfied and marked in related issue
• Relevant @unreleased tags included in DocBlocks
• Includes unit tests
• Reviewed by the designer (if follows a design)
• Self Review of code and UX completed

[kjohnson]

Cool seeing headers and links for pagination! This is often overlooked, but good that we are starting to leverage this feature.

I added some feedback on the queries. In particular, we have the CampaignDonationQuery which we should consider using - or at least update what is here to account for subscriptions and test payments.

[JasonTheAdams]

Out of curiosity, is the give-api namespace pre-existing? The -api suffix part feels redundant since this is part of the REST API path.

[glaubersilva]

@JasonTheAdams Yes, it's a pre-existing thing.

[JasonTheAdams]

I'm seriously considering recommending a give/v3 or something that deviates from the old REST API.