Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve error handling and usability of the admin API Backend form #160

Closed
GUI opened this issue Dec 8, 2014 · 1 comment
Closed

Improve error handling and usability of the admin API Backend form #160

GUI opened this issue Dec 8, 2014 · 1 comment

Comments

@GUI
Copy link
Member

GUI commented Dec 8, 2014

When admins are first starting to use api.data.gov, one of the first things they'll do is configure their API Backend. I had typically been configuring these in the past, but now that more agencies are setting things up themselves, a number of issues with this input form have come to light. The most common issues have been:

  • Missing the fact that servers need to be added under the "Backend" section.
  • Inputting the wrong thing into the host fields
  • Getting confused by vague error messages.
  • Publishing the backend and it not working.

What we need to collect in this form is pretty simple in most cases (where the API backend really lives and where you want it to appear to live on api.data.gov). However, there are a lot of optional settings to handle various other cases that make this form more complex. So while I think the overall UI could still be improved more significantly, I think we can do a variety of things to improve the usability of this form in its current incarnation.

As part of some updates I've pushed live today, I've tried to improve things by doing several things:

  • Adjust the UI of the form a bit to try to make the different sections more distinct and draw attention to the servers you have to add in the backend section.
  • Provide better automatic defaults, so when you enter a server, the backend host automatically populates with the same thing (since these do match 98% of the time).
  • Lots of improvements to the error validations. We were missing several validations for fields that should have been required, which often led to you thinking you had successfully created a backend, only to get bad gateway errors when you actually tried to use it.
  • Improve the display of validation errors. Most validation errors are now displayed as you enter the form fields, which really helps for some of the nested forms that were inside modals (those were hard to explain once you were out of that modal and then were hitting save). For the validations that we do have to perform server side, the error messages are now displayed in a slightly better way (at the top of the form in a container that will stick around, rather than in a modal which will disappear as soon as you click ok).
  • Additional hints have been added for a few settings we recommend but aren't required.

All in all, I think these updates will hopefully help make the process of creating a brand new API Backend less error prone for new people. There's still definitely improvements to make (I'd like to add more help tooltips), but this at least tackles some of the more significant underlying issues. With these main items out of the way, I'll plan to continue adding some more inline help and validations as questions come up.

@GUI
Copy link
Member Author

GUI commented Dec 8, 2014

Addressed by updates pushed live today.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant