List API Concept and Scalability of SKY APIs

Tom Klingman
Tom Klingman
Eighth Anniversary Participant Facilitator 1
in Blackbaud Raiser's Edge NXT® APIs
I'm interested in the List API. This query-based API may solve the long-standing problem of SKY API design that does not allow GET by a subset of records.


I see the potential of the List API - our developer will experiment with this soon.


I need to understand how scalable this API is and potential choke points with our business model.


Assume that we have 50 unique client websites* in Word Press that we want to integrate with RE/NXT data..


Each website has an average of 1,500 members each (client/website members identified by constituent ID).


LIST API allows us to GET a list that returns system ID.


Which we should be able to join to other entity endpoints (such as constituent) to display/publish on our client websites.


The standard developer API is limited to 25K calls a day and 10 calls a second. (With upgrades to 100K and 250K calls per day at $5K and $10K annually).


What do the calls or caps practically mean?


If a member logged into a private page on their website site, and we wanted them to have member search capability, how does the following scenario play out:


Member logs into WP

Goes to a search.

Asks to see all members in their group.


We would hard code the first part of the query (constituent attribute - client code 123)


Is the final count 1,500 (members) of records called 1,500 AND then an additional 1,500 (constituent endpoints such as preferred mailing address, primary email, etc.?)


If another member wants to perform this function immediately after, are the record counts called exactly the same as the first?


What is the number of List, Constituent, and Gift records which can be returned with each call/page?


I assume other factors play into how responsive API is (RE/NXT servers, Internet, number of users accessing the sites at the same time.


Ultimately, I'm trying to get a sense of how scalable this is for our business and potential choke points related to caps on calls/page returns by Blackbaud.


Thanks, any feedback appreciated and would love to hear from anyone with our business case challenges. Tom K.


Developers: I can't stress enough how hugely valuable it would be to include Output results to this API for our business (14 years w/BB) and I'm positive many developers!


Is there an insurmountable technical, administrative, or business reason why this can't be added (soon! - especially as this is still in BETA)? If so, what is that reason?


Thanks, Tom


*We support many fraternal groups and manage their data in a single segmented RE/NXT database (by unique constituent attribute.

Comments

  • Ben Wong
    Ben Wong Blackbaud Employee
    Tenth Anniversary Kudos 3 Name Dropper Participant
    Hi Tom Klingman‍,


    I think this is what would happen...assuming that you have a saved list in RE NXT for each of the client websites. I'm also assuming that the data is in a single instance of RE NXT.
    1. Call GET a list of lists to get the metadata for the list, not the records that are in the list. E.g. you will get the ID of the list, name of the list, description of the list, number of records in the list, etc. This will count as 1 API call from your 25k call limit.
    2. Determine which list ID matches the client website the member is logged into.
    3. Call GET Constituent list with the list ID as a parameter. This will return up to 5000 constituents per call. So if your list contains 1500 members for that particular website, you'll only need to make 1 API call.
    I believe you'll need to make these two calls with each member search. Of course, you can optimize by storing the list IDs in your app, since those probably won't change often.


    We have more details about how our API throttling works in this In-Depth article on API Request Throttling.


    Hope that helps!


  • Tom Klingman
    Tom Klingman
    Eighth Anniversary Participant Facilitator 1
    Ben,


    Our developer is starting to test out List API and so this is helpful, thank you!


    Is the 5K responses per call the same for all entities (gifts/addresses, etc.).


    I'll pass along the link w/coding you sent on throttling along to our web developer.


    My concern long term will be the calls/sec when we have multiple client sites with simultaneous peak traffic (as in fundraising appeals).


    I can't say yet say until we are deeper into testing, but right now it's something I have my eye on as possible choke point.


    Thanks, Tom








  • Ben Wong
    Ben Wong Blackbaud Employee
    Tenth Anniversary Kudos 3 Name Dropper Participant
    Hey Tom,


    I'm not sure off the top if all the entities have the 5k record limit, but I think most do. Gift list and Address list both have 5k limits.


    Let me know if you have trouble with the API limits when the application is in production.


    Thanks!
  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant
    Where in the SKY RE NXT UI Constituent Lists view can I find the List ID?


    There doesn't seem to be a properties dialog providing information about the list itself other than how many records there are and the filter options. The Constituent List tab's URI doesn't even seem to contain it. Given that it must be specified to get a list of Constituent via the API, having away to determine it would seem logical (Captain).


    Also, saving a list using Save as a new list simply renames the existing list rather than copying it to a new one. That's completely the reverse of expected behavior, eg Windows file Save As. This leads to the question, how can I make a copy of a list? Or am I missing something?

  • Jarod Bonino
    Jarod Bonino
    Tenth Anniversary Kudos 2 Name Dropper Participant

    Steven Cinquegrana:

    Where in the SKY RE NXT UI Constituent Lists view can I find the List ID?


    There doesn't seem to be a properties dialog providing information about the list itself other than how many records there are and the filter options. The Constituent List tab's URI doesn't even seem to contain it. Given that it must be specified to get a list of Constituent via the API, having away to determine it would seem logical (Captain).


    Also, saving a list using Save as a new list simply the existing list rather than copying it to a new list. That's completely the reverse of expected behaviour, eg Windows file Save As. This leads to the question, how can I make a copy of a list? Or am I missing something?

    The only place I'm aware of to see this ID in the UI is in the direct "Share" url:

    95f4bb58d40a14310c26b6eb6e68a8a5-huge-li

  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant
    Thanks Jarod. I just (re-)found it.


    Please consider adding it to the UI somewhere as I'm probably not the only one hunting it down.


    Any comments on list copying/save as? Can it be done?


    Cheers, Steve

Categories