Event API YAS*

Steven Cinquegrana

Very nice to see the new Event API (beta) make an appearance.


However ... [cue favorite bugbear theme music]


I just had a look at the OpenAPI definition and - surprise! - it's yet another take on an API schema departing markedly from the others.


Eg:


1. "v1" isn't in the base path where it should be but prepended to each path. So every call path is (unnecessarily) prefixed: /v1/events/{event_id}, etc. This like the School, Payments and Stat Unit APIs but not like the RE/FE APIs (which were standardized last year).


2. Operation IDs - which, again, were standardized in the FE and RE APIs with a degree of breaking-change pain last year - don't conform to the supposed standard: GetEventParticipantList instead of ListEventParticipants (correct).


I could go on, and you'll thank me for not, but, jebus, seriously? You have all of these APIs with different teams working in their own personal vacuums and seemingly no-one overseeing nought. It really does blow me away that Blackbaud can be putting such a messy bunch of stuff out there which results in extremely inconsistent code and behavior across the APIs when it is sooooo easy - in fact, easier - to adhere to a standard schema. And I'm waiting for the dreaded, "Announcing breaking changes to all OpenAPI definitions other than the FE and RE ones" which may come when someone at Blackbaud finally has to do some work consuming multiple SKY APIs in an in-house application. Nah, that will never happen.


***/5

Steve Cinquegrana | CEO and Principal Developer | Protégé Solutions


*Yet Another Schema

Stefan K

I just had a look at the Event API and we also ran into multiple issues where the new Event API doesn't follow the steps of the RE or FE ones.

1. By default only the ID field is returned in the data of the "Get event list" calls meaning we need to specify manually every single field we want to receive. This behavior is different from RE and FE where by default all fields are returned and the "fields" parameter can be used to reduce the amount of data returned.
2. "last_modified" field seems to be different in the Event API, in this one they are split in 2: "last_modified_to" and "last_modified_from". This also deviates from the standard that RE and FE uses.
3. Despite the documentation making it clear that the "Get Event List" API call "Returns a paginated list of events." it in fact does not. Specifying the "limit" parameter simply returns the amount you specify without including a "next_link" in the returned data. Inspecting the actual OpenAPI definition there is no mention of "next_link" anywhere. This also is completely different from the RE APIs where specifying "limit" properly generates the "next_link" parameter in the returned data. More importantly the "Get Event List" documentation is completely wrong on the "paginated" part as that feature doesn't seem to be implemented at all.

All in all, some of these points are just naming standards or defaults not being followed the same way in all the various APIs. And others, like the last one, simply doesn't provide the data as expected from the documentation.

Ben Regier

Seeing the same behavior here - the Get Event List endpoint returns only a series of IDs, not the additional information that the sample schema shows.

William da Silva

I think everyone (especially in this SKY Developper board) really appreciates new API releases with new endpoints.

Thank you BB for continuing to improve SKY API!


How can we (the community / partner network) help you (BB) reduce frustrations around some of these releases and help you output the most functional and usable API endpoints the first time?

We all have dev teams and live the same frustrations. Going back on code is costly and no one likes it and it's never a priority. Let's work together, I mean that's the basis of an API right?


Here are a few proactive ideas :

- Preview program (limited to partners, similar to the likes of Apple and such)

- Periodic and positive joint collaboration sessions between BB and Partner Dev teams


We are all on the same page, and we all want this going in the right direction.

Thoughts? Next steps?

William

Founder & CEO eSimpleIT

Ben Wong

Hey everyone,


We really appreciate this feedback. Please keep it coming! We're in the process of creating a dedicated Event API (beta) category to receive feedback, but until then this is the right channel.


We release APIs in "beta" to get feedback from a wider audience. While the API is flagged as a beta, we can take this feedback and iterate until we have something stable and provides enough functionality for it to be used in production applications. We won't get it right the first time, so this collaboration is important to help us improve the developer experience.

William da Silva‍, thanks for your suggestions. We do on occasion run preview programs limited to Partners, but decided this time to allow anyone to provide early feedback on the Event API (beta).


As for next steps, please keep the feedback coming and expect the Event API (beta) to improve over time. We'll continue to engage in the discussion here.


Thanks!

William da Silva

Thanks for the quick reply Ben Wong.


My apologies, I had not noticed (or even looked) to see that the API was in Beta.

Beta / limited preview, either way, I think this is great that BB is reaching out to the community and collaboration will only lead to success on "both ends of the API".


I also definitely agree that a "beta" category on the forum will help reinforce the "work in progress, feedback welcomed" aspect of new APIs in Beta.


Thanks!

William

Steven Cinquegrana

Hi Ben‍. I think initial beta releases should be a fair bit closer to some kind of internal standard than we've been seeing. As the Event API currently stands, it would need quite a lot of changes to come close to what I would regard as your most standardized APIs: the RE NXT or FE NXT APIs. And, as you know, even these API groups deviate quite a lot between each other with regard to ID types, the return of a next_link,etc, etc. And I include the OpenAPI definitions/documentation in this, which I think is reasonable.


It's much more efficient to provide feedback on a mostly-conformant initial beta release than on one where not a lot adheres to a standard schema. And, as I mention elsewhere, it's far easier to start from a standard schema; this, to a large degree, is what schemas are for. And I would consider the job of the SKY API overseer to ensure that a base schema is developed and adhered to by the disparate API development teams. That's a pretty fundamental development structure, I think.


Let me know when I can collect my award in the category Most Popular Community Poster With An API Development Team.

Ben Wong

Hey everyone,


Thanks for the feedback. We changed the following endpoints:

• Get Event List
  • We removed the last_modified_from and last_modified_to request parameters.
  • We removed the last_modified response field.
  • We now return most response fields by default when the fields request parameter is empty (excludes revenue and percent_of_goal).
• Get Event Participant List
  • We now return most response fields by default when the fields request parameter is empty (excludes total_paid, name_tag, seat, and memberships).

I know this doesn't address all the feedback in this discussion. There are some patterns that were introduced in the first SKY APIs for RE NXT and FE NXT that we feel we can deviate from and not bring them forward with future APIs. For example, not including the version in the base path allows us to version on the endpoint level for more flexibility.


We discussed the next_link implementation and decided that it was an uncommon approach with APIs in general. Developers should be more familiar with the approach of constructing URLs with limit and offset param values than expecting a URL supplied in the response. Does anyone feel like the next_link provides more value than constructing URLs with parameters?

David Zeidman

Good to see these changes Ben.


I have never like the next_link construct. I always prefer the limit with offset method as it gives me more control.

Stefan K

Ben Wong:

Hey everyone,


Thanks for the feedback. We changed the following endpoints:

• Get Event List
  • We removed the last_modified_from and last_modified_to request parameters.
  • We removed the last_modified response field.
  • We now return most response fields by default when the fields request parameter is empty (excludes revenue and percent_of_goal).
• Get Event Participant List
  • We now return most response fields by default when the fields request parameter is empty (excludes total_paid, name_tag, seat, and memberships).

I know this doesn't address all the feedback in this discussion. There are some patterns that were introduced in the first SKY APIs for RE NXT and FE NXT that we feel we can deviate from and not bring them forward with future APIs. For example, not including the version in the base path allows us to version on the endpoint level for more flexibility.


We discussed the next_link implementation and decided that it was an uncommon approach with APIs in general. Developers should be more familiar with the approach of constructing URLs with limit and offset param values than expecting a URL supplied in the response. Does anyone feel like the next_link provides more value than constructing URLs with parameters?

Thank you for these changes Ben. The 'next_link' implementation has been used for pagination in many different APIs (outside of Blackbaud), but like you said it is simple to just build it on our end, it's a nice to have.


The one field that is critical for us is: 'last_modified'. This field has to be included as we use it to grab only the data that was modified since the last time we called the API. It is also included in every single previous APIs that were released as far as I have seen on SKYAPI. Without this field there are no ways to simply get what was modified since the last time the API was called. This will force us to grab all the data from the Events every time we want to update our reports translating into more API calls, more bandwidth, etc... The last_modified field was a good way to limit the API call usage and bandwidth. We hope this field can be re-added.

Ben Regier

My understanding was that using next_link rather than limit and offset was a more reliable way to ensure that your result set had not changed in the the time between requests. But if that's not true and both methods are equally reliable, I don't see a problem with getting rid of next_link. Next_link can actually cause problems for people trying to use Microsoft's Power Platform, because the next link sometimes includes percent signs, which Microsoft automatically url-encodes, and then the link fails. So if limit and offset can be reliably used instead, I'll have a few less headaches!


I also agree that including the last_modified date in the results if very helpful for cutting down on calls and bandwidth.


Really appreciate all the work you're putting into this.


-Ben

Steven Cinquegrana

... not including the version in the base path allows us to version on the endpoint level ...

Really? You're thinking of versioning individual endpoints? Can you provide an example of another well-used API which does this as I'm not aware of any.

My understanding was that using next_link rather than limit and offset was a more reliable way to ensure that your result set had not changed in the the time between requests.

Though I, too, am not a fan of the next_link structure and don't use it - though I wouldn't say that it's uncommon - it was my understanding as well that it provided a way to deterministically retrieve contiguous lots of records immune to, say, the addition of a new record and that using limit + offset doesn't provide for that. Can you please clarify? (Meanwhile, today over on the School API, they've just rejigged their next_link response and gone to production, so I guess they don't share the same ideology as the Event API people.)

We removed the last_modified response field.

Why??

We removed the last_modified_from and last_modified_to request parameters.

So now there is no way to limit response results by date? What I think was suggested was making the filter consistent with other API endpoints such as Constituent List which provides a single last_modified request parameter. The intention is that this acts as a cut-off before which records are not returned.

Ben Wong

Thanks for the feedback. I confirmed that the last_modified field will be added back for both Participant and Event records/lists.


Thanks!

Steven Cinquegrana

Only the response fields? Or the request parameters as well?


An API schema would help with these things before they even got to beta, Ben‍.

Steven Cinquegrana

Ben‍ do you have a timeline on this change and a reply to my previous question?


Thanks.

Ben Wong

Steven Cinquegrana‍, the last_modified will be added to request and response for Participant List and Event List. The work is being planned now so I expect something to be released this month.