Developers are increasingly aware of the need to consider accessibility when designing their applications. But few are aware that this can extend to API, and schema design, too.
While there is lots of guidance for API design around security, documentation, standards, and technology, there's little said about accessibility.
In this piece, I'm going to look at a couple of challenges in API and schema design that can be improved with easy-to-adopt habits in your design process.
- Word separators
Word separators and assistive technology
One of the most important considerations for accessible API discovery is how your naming conventions interact with screen reader technology.
Here is a snippet of some properties found in the spec, related to the data payload of the event.
We can see two different naming conventions in place for the properties.
datacontenttypeuses an all-lower-case, no-spaces format.
data_base64separates words with an underscore.
The first of these is opaque to screen readers - it can't tell where words begin and end. The second is easily interpreted by screen readers.
The golden rule is: use word separators
Popular choices in JSON-based API and schema design include:
In IDs and similar entities
use.dot.separators(often with reverse-dns prefixes)
use/path/separators(often with URIs/IRIs)
use-hyphen-separators(often with GUIDs and similar)
An ancilliary benefit is that code generators can more easily produce idiomatic naming that conform to the casing conventions in the target language/platform.
|Dotnet with additional suffix
Another common challenge is the use of abbreviations. While a user interacting with your API may recognize your abbreviations from context, a screen reader may not be able to do so, especially if your abbreviation is not a common one.
While it might be visually clear that
pvtKey is equivalent to
privateKey a screen reader will almost certainly have to spell out
p-v-t-key which is both slower, and requires much more cognitive load.
These are just two simple habits you can adopt in your API and schema design to help with inclusivity and accessibility - with the added benefit of helping out other types of tooling over your codebase.
I'd love to hear of your experiences and suggestions for other things1 that we can do to improve in this area.
The need to distinguish
Iin human-readable URIs or identifiers is one I'm thinking about.↩