How to design APIs for Accessibility

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.

1. Word separators
2. Abbreviations

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.

Let's consider the CloudEvents JSON schema. I'm only picking this because it has a couple of good examples for us to look at - you don't need to know anything about CloudEvents per se.

Here is a snippet of some properties found in the spec, related to the data payload of the event.

{
    "datacontenttype": {
        "$ref": "#/definitions/datacontenttype"
    },
    "data": {
        "$ref": "#/definitions/data"
    },
    "data_base64": {
        "$ref": "#/definitions/data_base64"
    }
}

We can see two different naming conventions in place for the properties.

• datacontenttype uses an all-lower-case, no-spaces format.

• data_base64 separates 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:

1. use_underscores
2. useCamelCase
3. use-kebab-case

In IDs and similar entities

1. use.dot.separators (often with reverse-dns prefixes)
2. use/path/separators (often with URIs/IRIs)
3. use-hyphen-separators (often with GUIDs and similar)

Ancilliary benefits

An ancilliary benefit is that code generators can more easily produce idiomatic naming that conform to the casing conventions in the target language/platform.

For example:

Abbreviations

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.

For example:

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.

Takeaways

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 things¹ that we can do to improve in this area.