Improving Validation Errors in API Clients

At DNSimple, as engineers and DNS experts, we know having to deal with error conditions isn't easy or pleasant. Developer toolkits and documentation play a critical role in the implementation process — they can make a difference and reduce the burden of handling external failure conditions in your infrastructure or application.

To that end, we've been working to improve the developer experience in our API error handling, especially when dealing with validation errors while performing API calls to our API endpoints.

Today, we're excited to announce several improvements to the user experience of managing resources, directly or indirectly, via our API.

Exposing validation errors in API clients

When submitting API calls to create or update resources, our system validates the API payload before processing the request. If any of the payload values are invalid, our API returns a HTTP 400 error with the message: Validation failed.

The API response JSON payload also includes a node that contains the list of invalid attributes, along with the specific reasons they were rejected. While this data has always been in the API responses, our API clients ignored it and only exposed the high level error messages, making it even harder for users to understand what went wrong.

We've now updated all 9 of our API clients to properly expose validation errors. While the specific implementation varies depending on the language, we tried to keep the developer experience consistent across all clients. The collection of errors is available in a new attribute_errors dictionary (aka Hash, Map, etc), accessible from the error object/structure returned in case of a failed API response.

This is an example in Ruby:

begin
  client.domains.create_domain(account_id = 63, name: "notadomainname")
rescue Dnsimple::RequestError => e
  puts e.message
  puts e.attribute_errors.inspect
end

# Output:
#
# Validation failed
# {"name"=>["is an invalid domain name"]}

And this is an example in Go:

domainResponse, err := client.Domains.CreateDomain(context.Background(), "63", Domain{Name: "notadomaninname"})

var errorResponse *ErrorResponse
if errors.As(err, &errorResponse) {
  fmt.Println(errorResponse.Message)
  fmt.Println(errorResponse.AttributeErrors)
}

// Output:
//
// Validation failed
// map[name:[is an invalid domain name]]

You can find more examples in the individual client repositories:

• https://github.com/dnsimple/dnsimple-go/
• https://github.com/dnsimple/dnsimple-ruby/
• https://github.com/dnsimple/dnsimple-node/
• https://github.com/dnsimple/dnsimple-java/
• https://github.com/dnsimple/dnsimple-elixir/
• https://github.com/dnsimple/dnsimple-php/
• https://github.com/dnsimple/dnsimple-csharp/
• https://github.com/dnsimple/dnsimple-rust/

Exposing validation errors in HashiCorp Terraform DNSimple provider

Many of our customers use the DNSimple Terraform provider to automate the configuration and provisioning of DNS records. Not surprisingly, the confusion about validation errors was one of the most recurring topics.

We've updated the Terraform provider to expose the full validation explanation in case of validation failure. Say goodbye to the generic, vague, and unfriendly Validation failed message.

You can now update to version 0.14 to take advantage of friendlier error messages.

Improving API error documentation

While working on the code changes for the API clients, we realized many failure conditions were not properly documented in our developer site. We took the time to thoroughly review our documentation and make some important improvements. The developer site now includes a more comprehensive explanation of errors. We updated our overview section on errors to include more examples, listed by HTTP status code. We also added a section on each endpoint that cross-links the overview section.

Visit our developer site to view the updates.

The OpenAPI definition has been updated to reflect the structure of all error types. It wasn't previously reflecting the structure for validation errors, which now includes not only a message in the payload, but also an errors array with more detailed information.

You can download the updated OpenAPI schema definition in our developer documentation:

• YAML
• JSON

Conclusion

DNSimple provides API clients in several languages to facilitate the integration with our domain and DNS API. We're committed to continuously improving our API, because we want to offer the best possible domain management automation experience for you – our customers – when integrating your infrastructure with the DNSimple services.

We sincerely appreciate all the feedback you've provided over the years about our API experience, and we can't wait for you to take advantage of the new API validation error improvements. If you're not using DNSimple yet, give us a try free for 30 days. And as always, if you have more questions or feedback, get in touch — we'd love to hear from you.

Share on Twitter and Facebook

Simone Carletti

Italian software developer, a PADI scuba instructor and a former professional sommelier. I make awesome code and troll Anthony for fun and profit.