API feedback on round trips and N+1 queries

API Support
1

Just wanted to provide a couple bits of constructive feedback on the Dwolla APIs after having used them for a couple weeks.

The first is that having HTTP 201 redirect responses for resource creation (e.g. Customer or Beneficial Owner) is not optimal. I can’t imagine a scenario where someone creates a Customer and then doesn’t care about the status of that customer - we need to know the status right away in order to inform the user if they need to retry their submission, or if they need to upload documents (document status), etc. So what this means is that every time I’m creating these resources I’m immediately making another API call to fetch the resource’s info. This round-tripping instantly doubles the response time for creation requests.

It would be preferable to just get an HTTP 200 with the resource’s data included in the response body.

The second thing is it would be nice to be able to fetch all the resources related to a customer in a single API call, e.g. when I fetch a Customer it would be nice to be able to get the uploaded Documents, Beneficial Ownership Certification, the Beneficial Owners, the Beneficial Owners’ Documents, etc. all back in one blob. As it stands right now, I have to make a bunch of separate API calls to fetch all this info (which happens in my app when one of my users goes back into a partially-completed Customer signup, or if they want to edit their completed Customer info). Some of these requests also involve round-tripping, such as when I’m fetching the beneficial owners’ documents - first I have to fetch the list of beneficial owners, then for each beneficial owner response, I have to make a separate API request to load that beneficial owners’ documents. In the context of relational databases this is an anti-pattern known as the N+1 selects/query problem.

For example right now when I reload a partially-completed Customer signup page for a Customer w/ 3 beneficial owners, I’m waiting on 7 separate API requests before the page is fully loaded:

GET https://api.dwolla.com/customers/{id}
GET https://api.dwolla.com/customers/{id}/documents
GET https://api.dwolla.com/customers/{id}/beneficial-ownership
GET https://api.dwolla.com/customers/{id}/beneficial-owners
  GET https://api.dwolla.com/beneficial-owners/{id1}/documents
  GET https://api.dwolla.com/beneficial-owners/{id2}/documents
  GET https://api.dwolla.com/beneficial-owners/{id3}/documents

It would be preferable to have just one GET https://api.dwolla.com/customers/{id} that returns all the sub-resources in one go.

If you’re worried about bloat, certain APIs I’ve worked with by default just provide the IDs of linked resources in the response, but also support an “expand” parameter that lets you specify the related resources you’d like to be fully expanded in the response.

I hope if Dwolla releases a v3 API these items will be considered. Thank you.

2 Likes
2

Hi @abe, Thanks for providing detailed feedback on working with the Dwolla API! These are a few items I’ve heard while working with other developers and each come with their own bit of complexity. I’ll be sure to relay these on to our Product team for future consideration on API enhancements! For #2, we’ve explored the use of _embedded (link to HAL spec), which would be an array of relational resources. I think there are a few different options here which we could take a look at that would reduce the overall number of calls required to get the data that you need.

We’ll keep both of these in mind as we look to enhance the API and there may be a way to introduce the latter request in a non-breaking way. Thanks again for your feedback! :slight_smile:

1 Like
3

I think I saw in another comment that Dwolla may be doing some feature planning for the next year? If so I’d like to humbly re-up my wish for the “expand” API capability - it’s something I still wish I could do today. :innocent: Thanks