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.

[JasonTheAdams]

Left some thoughts, @glaubersilva! Great work!

[rickalday]

Passed manual QA tests.

[JasonTheAdams]

@glaubersilva Why did this go to QA with requested changes pending? 😅

[glaubersilva]

@JasonTheAdams It didn't go to QA. I think @rickalday got confused because this PR is related to other tasks that were to QA

[JasonTheAdams]

Hahah! Got it. 😆

[rickalday]

@glaubersilva Why did this go to QA with requested changes pending? 😅

My bad. I posted on the wrong PR.

[JasonTheAdams]

@glaubersilva Why did this go to QA with requested changes pending? 😅

My bad. I posted on the wrong PR.

[glaubersilva]

@JasonTheAdams I liked the idea of renaming /give-api/v2/ to /give/v3/ for new routes, aligning with the new approach we introduced in the Campaigns domain. This change would ensure consistency across all implementations using the new standards, which are designed to support entities.

I believe it would be appropriate to apply this replacement everywhere, including the routes implemented in this PR as well as those for Campaigns.

So, I think we can move forward with this change unless the other devs have concerns or objections about it, let's check with them just to make sure we are not missing something here.

[JasonTheAdams]

Sounds great, @glaubersilva! I like the idea of retroactively applying this so long as the endpoints we're applying them to are:

1. Truly RESTful
2. Not in production

[JasonTheAdams]

@glaubersilva Do we have any restrictions around this parameter? If our goal is to protect anonymous donations, then we may want to include some permission parameters around this. Presently, this is a fully public API, and these parameters are discoverable, so it's not hard for someone to flip the switch on this. There are a few contexts, here:

1. Donor wall
2. Admin list tables (donations list and campaign donations)
3. Campaign donations
4. 3rd Party usage

I'm guessing this will result in 3 forms of output:

1. Anonymous donations are included and donor info revealed (admin-side)
2. Anonymous donations are included but donor information is redacted (donor wall)
3. Anonymous donations are prohibited

Now, we may actually be fine with anyone in the world being able to query anonymous donations so long as the donor information is redacted (dropping option 3). But we'll still need a way to grab all information for the admin side with proper authorization.

Note: this is true of both the collection endpoint and single donation resource endpoint.

cc: @jonwaldstein