Release News: Church Volunteer API (beta)

Alyssa Maslankowski

The Church Volunteer API (beta) was released on 07/08/2020. The API enables developers to manage volunteer, opportunity, and position information in Church Management. This initial release includes endpoints to add, edit, and delete volunteers, opportunities, and positions. It also includes endpoints to manage teams, requirements, assignments, and emergency contacts.


For more updates, see the changelog. 

Steven Cinquegrana

I noticed that the root namespace for this API is "volunteer" rather than "churchvolunteer". Does this not create a possible confusion if another volunteer API is added later, say, "Event Volunteer"? No problem if not, just a question.

Steven Cinquegrana

The OpenAPI definition for this API generates some very weird model objects compared to other APIs.


For example models from the Constituent API look like this:

ConstituentAdd, ConstituentEdit, etc.


Models from the Church Volunteer API look like this:

BlackbaudVolunteerSkyApiServiceServiceClientsVolunteerDataServiceVolunteerAdd, BlackbaudVolunteerSkyApiServiceServiceClientsVolunteerDataServiceVolunteerEdit, etc.


This means that derived code objects are ridiculously unwieldy. Would whoever created the definition please consider using a schema more like one of the more mature APIs, such as Constituent?

 

Luke Stitzinger

Thank you so much for pointing this out so we can tidy up these names Steven. We have story pulled into our next sprint to clean these up.

Steven Cinquegrana

Luke Stitzinger‍ can we assume that the names will have the "BlackbaudVolunteerSkyApiServiceServiceClientsVolunteerDataService" part lopped off the front, leaving names like VolunteerAdd and VolunteerEdit? If so, we can make a manual edit and publish the API to our SKYLib.NET library.


And will the namespace remain "volunteer" or will it change?

 

Paul Gibson

Hi Steven.  Yes, we are going to keep the namespace as "volunteer".  I'll be transparent about our thinking on this in the interest of giving some context to the choice we are making.  This API is currently specific to our Faith vertical product "Blackbaud Church Management" and so we have tried to make the name and description in the documentation clear about that to avoid any confusion about what product it will work with.  This api works over entirely new data structures and services that were created entirely new for the Church Management product and thus have no overlap with any classic RENXT volunteer capabilities.  However, we anticipate that at some point in the future these capabilities could become available in other vertical product offerings unrelated to Church Management but powered by the same underlying services.  So for example, in the same way that today you can use the Constituent API for both RENXT and Church with zero code changes we want to anticipate supporting that kind of compatibility way down the road with code you write for this new (church) volunteer api.  So consider this sort of the next-gen Volunteer API, debuting first for Church Management.  And while there are no plans on record at this time to bring this to other products besides Church Management, from the api standpoint we want to anticipate that potential and avoid prematurely locking in a name that restricts the api to the Faith vertical.

Steven Cinquegrana

I just noticed that you have the API version prefixing each element path rather than the base path.


Eg

Church Volunteer API

Base path: /volunteer, Element path: /v1/volunteers/{volunteer_id}

Constituent API

Base path: /constituent/v1, Element path: /constituents/{constituent_id}


This seems to be quite a random thing with the SKY APIs. The base path should contain the version, ala the General Ledger, Account Payable, Constituent, etc APIs and NOT like the Event, School, Payments, etc APIs. You would only have the version in the element paths if you intended to individually version endpoints and that's a pretty strange thing to do. In any case, the variation between APIs represents a whole bunch of unnecessary inconsistency.

 

Luke Stitzinger

Afternoon Steven Cinquegrana‍,

We just updated the API names. Take a look and let us know what you think!

Steven Cinquegrana

Much better, Luke Stitzinger‍ , thanks. You still have the version (v1/) in the element path but I guess that's your call.