Understanding simplified customer onboarding through a better-formed API—pun absolutely intended.

At Dwolla, our API is our bread & butter, so we’re always trying to improve the usability and decrease the time it takes for our customers to go live. One way we accomplish this is by building our own products on top of the same APIs that we expect our customers to use.

For example, the Dwolla Dashboard & Admin is built almost entirely using our API V2. From the very beginning, we knew we wanted to broaden the functionality of this dashboard—specifically, we knew we wanted our white label Clients to have the ability to edit customers within the dashboard.

Editing Customers in the Dashboard

When we first started adding the edit functionality, we quickly realized we were going to be duplicating a lot of the logic that was already in our API to determine what fields needed to be submitted for all types and statuses of customers.

We really wanted a way for the API to tell us the information we needed to show the user, based on the current state of the customer being edited.

To do so, we needed dynamic form definitions based on the state of the API resources. Since our API is hypermedia-driven and an implementation of the HAL spec, we wanted something that aligned with how our current responses are represented.

After some research, the obvious answer was to use the HAL-FORMS Media Type, but after some prototyping we quickly realized it wasn’t going to fit our needs as we’d hoped.

Features we considered important for usability of the generated HTML were missing, such as: providing a set of accepted values for a dropdown, hints on the field type and custom validation rules. These limitations inspired us to take some of the best ideas of HAL-FORMS and expand upon them.

Dwolla HAL-Forms describes how we decided to represent forms in the API and it starts with the media type. Similar to our error responses, which we represent using vnd.error, the form responses don’t deviate much from HAL, so we’re including it as a profile link.

When this profile is provided in the Accept header of the request, the API knows that you’re looking for a form for the given resource. So how is a client expected to know if a form is available for a given resource? Links!

This is a RESTful API after all. In order for the forms to be discoverable, we include links in the resources to the forms.

So when a customer is retrieved, an “edit-form” link is now included in the _links object of the response.

GET /customers/1bdcf411-4a81-4534-993b-9ba183a3b3dc HTTP/1.1 Accept: application/vnd.dwolla.v1.hal+json

Following that link and using the given type (with the form profile) as the Accept header returns the form that defines how and what can be updated for the customer. It describes where to post the form, how to build the request body, and what Content-Type header should be included.

GET /customers/1bdcf411-4a81-4534-993b-9ba183a3b3dc HTTP/1.1 Accept: application/vnd.dwolla.v1.hal+json; profile="https://github.com/dwolla/hal-forms"

This response then gets translated into a form for editing customers in Dashboard & Admin!
If the customer gets put into the document or retry state while being verified, the form may change with just the fields that are needed to get the customer to a good state (e.g. address, DOB, SSN, etc.).

The dynamic nature of the forms also works for creating customers. If you make a request to “/customers” with the form profile, you’ll get a response that includes multiple forms you can choose from based on the type of customer you’re trying to create.

The benefits of this approach are numerous as developers won’t need to spend time interpreting Dwolla’s business rules and how to apply them based on the state of a given resource in order to generate a user interface. Simple validations, accepted values and input labels are all provided out of the box.

Currently forms are only returned for creating & editing customers, but we’re looking forward to expanding them across our existing and future endpoints.

Learn more about Dwolla’s ACH API here or view our developer documentation.


Stay Updated