Skip to content
Matthew Adams By Matthew Adams Co-Founder
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.

Programming C# 12 Book, by Ian Griffiths, published by O'Reilly Media, is now available to buy.

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 Introduction to Rx.NET 2nd Edition (2024) Book, by Ian Griffiths & Lee Campbell, is now available to download for FREE.

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:

JSON Dotnet Dotnet with additional suffix
datacontenttype Datacontenttype DatacontenttypeEntity
dataContentType DataContentType DataContentTypeEntity

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:

Abbreviated Not abbreviated
pvtKey privateKey

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


  1. The need to distinguish O and 0 or 1, l, and I in human-readable URIs or identifiers is one I'm thinking about.

Matthew Adams

Co-Founder

Matthew Adams

Matthew was CTO of a venture-backed technology start-up in the UK & US for 10 years, and is now the co-founder of endjin, which provides technology strategy, experience and development services to its customers who are seeking to take advantage of Microsoft Azure and the Cloud.