Query API Feedback

David Zeidman

Here are some initial thoughts about the new Query API:

• I think there needs to be some explanation about the three different “Query Execution Job” entries in the list of endpoints. It took me a while to realise what the difference was between them. (I eventually understood that you could run a query on the fly with the query json as the payload - that is a great addition by the way - and that GET ought to be getting the result as POST to start a query job but it was not obvious)
• Many of the links within the API endpoint page pointing to objects do not work. For example (and this is one of, well, all of them that I tried) : https://developer.sky.blackbaud.com/api#api=query&operation=StartQueryExecutionJob&definition=AdvancedProcessingOptions

did not actually go to the Advanced Processing Options topic.

• There is a lot of explanation as to how to get results etc which is great but it is not always overly clear. I am still not clear as to why getting the results of a query can be synchronous or asynchronous. In both cases you are polling the results. I would have assumed a synchronously run query would return the results in the same way as it would when calling, say, get constituent list endpoint.
• Under the section FilterFieldWrite→FilterOperator, it refers to the operator values as “equal, not equal, etc.). This is really imprecise. It is not possible to put ”etc" into an endpoint query. Please ensure all possible values are included. Of course it is possible to guess but the point of documentation is to be exact so that we don't have to guess.
• Please add webhooks for every new API. This should be a design principle. (I have added this to the ideas bank too)

I have just started investigating so I may encounter more suggestions / issues but thanks for implementing this. It is and will be very useful indeed.

Alex Wong

@David Zeidman
Blackbaud is receiving feedback through using IdeaBank, so you can post there, or check feedbacks from others.

I do agree with you that the docuemtation can be a lot better. I was part of the EAP as well as pre-EAP testing of Query API, and had to do a lot of “trying out” on each of the endpoints.

The error on “link” to the entity object is broken (I reflected that a few times now) since the new API docuemtnation interface. currently as workaround I need to copy and do Ctrl-F to find the entity to get to it, or just scroll. very not friendly and not the intended experience of the docuemtnation. I call it a bug on the API reference new interface.

Heather McLean

@David Zeidman - thank you! Yes, Alex is correct. If you wouldn't mind submitting these to the Ideas as the Product team is actively reviewing and planning improvements accordingly. Thank you so much for this feedback.

David Zeidman

@Heather McLean OK, I have moved the points over to the idea page with the exception of the page links which I assume is a known issue so I did not want to repeat it.

Just as an FYI - you did write at the bottom of your post:

Providing feedback:
We also encourage you to ask questions and leave feedback in Blackbaud Community, and to submit all ideas for improvement to the API or the documentation in our Idea Bank. There is a new Idea Bank category available specifically for the Query API.

That is why I posted feedback here in the community rather than on the ideas page.

Lee Grisham

@David Zeidman @Alex Wong have you all seen any issues with duplicates when using the Query API? After the PUB yesterday, I don't understand why Query was the API instead of Reports/Exports when they are usually the preferred method of exporting data out of RE/FE.

Am I missing something? Definitely a beginner in this area, but admire what you both do.

Alex Wong

@Lee Grisham
I hear from a lot of people including Blackbaud that Query shouldn't be used for exporting data from RE, however, I do not agree with that statement. I actually does 95% of my data export from Query, not from Export module.

Query is powerful in itself, so is Export, but they serve “different purpose” and it all depends on your use-case. For example: you will want to use Gift Query to export a list of all installments information (installment date, amount, etc) rather than use Export (rows of data, vs pre-determined specific # of installments in columns of data)

I would assume BB will work on Export capability on webview and SKY API, I also expect them to work on Import as well.

back to directly answering your question about duplicates. Query has the potential to give you duplicates result depending on what you filter/output/sort on. Any use of ONE-to-MANY relationship fields is potential for dup rows. So if the database query output will give you dup rows, the SKY API Query will give you the same.