Ook je REST API mag toegankelijk en inclusief zijn

15-10-2024

We denken uitsluitend aan front-ends wanneer we het hebben over toegankelijkheid en het werken aan inclusieve websites, maar je kunt ook verschillende richtlijnen volgen om een stap verder te gaan en je API te ontwerpen met toegankelijkheid in gedachten. Hier zijn 10 tips die ik graag wil delen:

1. Duidelijk, consistent en intuïtief API-ontwerp

Zorg ervoor dat het API-ontwerp de REST-principes volgt en voorspelbaar is.

Gebruik consistente naamgevingsconventies voor endpoints, parameters en resources.

Houd je aan algemeen geaccepteerde conventies (bijv. meervoudsvormen voor resourcenamen). Bied een duidelijke structuur die gemakkelijk te begrijpen en te gebruiken is, waardoor de cognitieve belasting voor gebruikers met cognitieve beperkingen wordt verminderd.

2. Uitgebreide Documentatie

Bied grondige, duidelijke en toegankelijke API-documentatie aan in meerdere formaten (bijv. HTML, Markdown, PDF).

Inclusief voorbeelden van verzoeken en reacties, inclusief randgevallen.

Zorg ervoor dat de documentatiewebsite voldoet aan de WCAG 2.1-normen, met functies zoals toetsenbordnavigatie, ondersteuning voor schermlezers en duidelijke koppen.

Overweeg een audioversie of interactieve tutorials aan te bieden om de documentatie toegankelijker te maken voor personen met visuele of leerstoornissen.

3. Beschrijvende en Actiegerichte Foutmeldingen

Maak foutmeldingen duidelijk, beschrijvend en actiegericht. Vermijd cryptische codes of berichten die extra context vereisen.

Geef duidelijke informatie over hoe problemen kunnen worden opgelost, zodat ontwikkelaars begrijpen wat er mis is gegaan en hoe ze het kunnen verhelpen.

Gebruik standaard HTTP-statuscodes (bijv. 400 Bad Request, 404 Not Found) met gedetailleerde beschrijvingen.

4. Lokalisatie en Internationalisatie

Ontwerp de API zodat deze eenvoudig kan worden gelokaliseerd en aangepast aan verschillende talen, culturen en regio's.

Ondersteun meerdere talen voor foutmeldingen en documentatie, en sta datum-, nummer- en valutavormen toe die conform zijn aan verschillende locale instellingen.

Overweeg ondersteuning voor rechts-naar-links (RTL) talen waar van toepassing.

5. Ondersteuning voor Hulpmiddelen

Zorg ervoor dat je API compatibel is met hulpmiddelen zoals schermlezers, die sommige ontwikkelaars met een visuele beperking mogelijk gebruiken om door de API-documentatie of output te navigeren.

API-responses moeten zo gestructureerd zijn dat ze gemakkelijk kunnen worden geparsed en hardop gelezen door schermlezers.

Consistente en duidelijke indeling van JSON/XML-responses is hierbij essentieel.

6. Rate Limiting en Transparantie over Hulpbronnengebruik

Implementeer eerlijke rate limiting- en quotabeleid om ervoor te zorgen dat gebruikers met tragere systemen of netwerken (vaak in gebieden met lage inkomens of landelijke gebieden) niet benadeeld worden.

Bied duidelijke feedback wanneer limieten worden bereikt, samen met suggesties over hoe gebruikers hun verzoeken kunnen optimaliseren of opnieuw kunnen proberen na een bepaalde periode.

7. Aanpasbare Responseformaten

Bied API's aan die gegevens teruggeven in meerdere formaten (bijv. JSON, XML, CSV) zodat gebruikers met verschillende behoeften of hulpmiddelen het formaat kunnen kiezen dat het beste bij hen past. Ondersteun queryparameters of headers om het antwoordformaat te specificeren.

8. Minimale Cognitieve Belasting voor API-interacties

Verminder het aantal stappen of velden dat nodig is om een geldig API-verzoek te doen.

Vermijd te complexe queryparameters of diep geneste JSON-objecten.

Maak responses beknopt en gestructureerd zodat gebruikers met cognitieve beperkingen de gegevens gemakkelijk kunnen verwerken.

Bied duidelijke instructies in de documentatie over verplichte en optionele parameters.

9. Versiebeheer en Achterwaartse Compatibiliteit

Gebruik correct versiebeheer (v1, v2, enz.) om ervoor te zorgen dat gebruikers die afhankelijk zijn van oudere versies van de API niet plotseling worden buitengesloten of gedwongen worden om te upgraden, wat verstorend kan zijn, vooral voor gebruikers met minder middelen om zich snel aan te passen aan veranderingen.

Documenteer breaking changes duidelijk en geef van tevoren een waarschuwing voordat oude versies worden uitgefaseerd.

10. Veilige Authenticatiemethoden

Gebruik veilige, standaard en algemeen geaccepteerde authenticatiemethoden (OAuth2, OpenID Connect, enz.) en zorg ervoor dat ze gemakkelijk te implementeren zijn.

Vermijd te complexe authenticatieworkflows die gebruikers die afhankelijk zijn van hulpmiddelen kunnen uitsluiten.

Overweeg ondersteuning voor multi-factor authenticatie (MFA) toe te voegen, wat de beveiliging verhoogt, maar implementeer het met toegankelijkheid in gedachten (bijv. MFA via SMS toestaan voor gebruikers die geen toegang hebben tot andere apparaten).

Bied duidelijke en eenvoudige richtlijnen over hoe om te gaan met authenticatie en tokenvernieuwing.

Bonus: Inclusieve Taal in API-documentatie en Responses

Zorg ervoor dat de documentatie en foutmeldingen van je API inclusieve taal gebruiken. Vermijd termen die als bevooroordeeld, gendergericht of beledigend kunnen worden ervaren. Vermijd aannames over de achtergrond, vaardigheden of culturele context van de gebruiker in zowel het API-ontwerp als de gebruikte taal in de documentatie.

Laten we die extra stap zetten en de 20% van onze bevolking bereiken die een toegankelijke wereld verdient.