Change To The Constituent API

Kimberly Coughlin

We updated the SearchConstituent endpoint to support email_address in the search_field request parameter. Previously, search_field only supported lookup_id.


For more information, see our changelog.

Heather McLean

This is great news!

Steven Cinquegrana

Can someone please confirm that this latest Constituent API change included some changes to the OpenAPI Definition?

We're seeing build errors such as:

Constituent.Model.ApiCollectionCustomFieldRead changed to Constituent.Model.CustomFieldReadApiCollection

Constituent.Model.ApiCollectionConstituentListItem changed to Constituent.Model.ConstituentListItemApiCollection

It looks like this change is across the board for all ApiCollection types.

We can deal with but it makes things difficult for users of our SKYLib.NET code library and SDK, effectively constituting a breaking change to their code.

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

Michael Reece

Steven,

An unrelated changed renamed some of the complex objects within the OpenApi definition for this API. Some of the previous names did not conform to OpenApi rules. While we do try to limit these types of changes as they can be a major inconvinence, they are not considered breaking. Our breaking changes policy is posted here. These renames fall under the information note in blue in that documentation. Our main goal is to ensure no runtime code breaks and your current customizations can keep running.

Steven Cinquegrana

@Michael Reece Thanks for your reply. Can you point me to the OpenAPI rules that cover the naming issue? Also, the various SKY APIs already use quite a variety of collection specifiers, from ModelNameCollection, to ApiCollectionModelName, to no specifier at all. The Constituent API is the only one that uses ModelNameApiCollection as far I can see, so I'm a bit confused as to why there was a pressing need to change.

Michael Reece

Sure @Steven Cinquegrana. The issue was with complex objects like the ones you referenced. Originally the definition for that field was emitting ApiCollection[CustomFieldRead] and the square brackets were violating RFC3986 for 2.0. Those are now named in the format of ApiCollectionOfCustomField.

Steven Cinquegrana

@Michael Reece Have you changed the definition again? We're now seeing ApiCollectionOfCustomField in the raw definition file which has resulted in further code changes we've had to make. Please confirm.

Steven Cinquegrana

Thanks @Michael Reece . Did you mean CustomField_ApiCollection? This is what I see in the raw definition file. And does this mean that there will be further changes like this to other APIs? Eg, the Gift API is still showing ApiCollection[CustomFieldRead], as do many others, though some - such as the Webhooks API - don't use any Collection naming at all. I don't really care apart from the disruption, resulting code breaks and lack of notice/change documentation.

Michael Reece

Correct. The original change you saw went out in the second half of last week. An issue was discovered Friday and was resolved with the latests change on this Monday (4/25). There are no further planned changes for naming in the Constituent API area that i am aware of. Other areas like Gift that you mentioned have the original issue with special characters and those will likely be updated to correct the rule violation but this work is not yet planned.

Steven Cinquegrana

Right. Thanks. We'd definitely appreciate some notice on these changes if at all possible. Even if Blackbaud doesn't consider them to be of much consequence, over on the other side of the development fence, they cause issues.