10 handvatten voor het Design van een (Drupal) Web API

03 Jun 2015

Erik de Kamps
Drupal developer
+31 (0)20 - 261 14 99

Een Web API (Application Programming Interface) is een applicatie die niet visueel zichtbaar is voor de gebruiker. Er wordt gebruik gemaakt van verzoeken (requests) en antwoorden (responses). Deze interface wordt voor bijvoorbeeld mobiele apps of e-mail notificaties gebruikt.

Het bouwen van deze applicatie is voor het grootste gedeelte gelijk aan de ontwikkeling van een software project. Er werken technische en non-technische mensen mee zoals designers en ontwikkelaars.

API's voor niet-technische mensen

Wanneer gewerkt wordt aan een software project kan de communicatie met mensen die geen code schrijven lastig zijn. De programmeur schrijft dan namelijk uren code, de non-technische partij snapt hier weinig van.

Om toch een beeld van voortgang te kunnen tonen kan een visueel design gebruikt worden. Hierin wordt de architectuur en implementatie gepland en de details verfijnd.

API's zijn het hart van vandaag

Communicatie of integratie tussen systemen zijn niet altijd netjes, maar het is het hart van de meest belangrijke systemen op het web vandaag. Overheden, scholen, bedrijven, ziekenhuizen en sociale media worden steeds meer gebouwd op API's. Ze worden verrijkt tot het punt waarop twee of meer systemen inhoud en diensten kunnen combineren.

Integratie van API's

Het samenvoegen hiervan heeft duidelijke communicatie en planning nodig. Dit om te voldoen aan de technische wensen van twee verschillende teams binnen één applicatie. Wanneer het om een publiekelijk platform gaat kan het hier om honderden of zelfs duizenden teams van ontwikkelaars gaan. Hoe kan je ondersteuning bieden aan de uiteenlopende technische vereisten van al deze API gebruikers zonder met iedereen te hoeven communiceren?

De API moet flexibele functionaliteit bieden zonder specifieke indeling, het moet intuitief zijn. Er wordt geleund op de API om de wensen te kunnen realiseren. Hiernaast is een goede documentatie nodig om alle functionaliteit te beschrijven. Een overzicht dat gedeeld zou moeten worden met de community.

10 Handvatten voor API design

Stel, je hebt een opzetje van je design specificatie gemaakt maar weet niet precies waar je op moet letten. Hieronder tien punten om na te leven:

1. Hou het simpel

Een goed technisch plan zou eenvoudig moeten zijn. Dit is de manier waarop bedrijven vaak werken. Dit geld ook voor een design. Je kunt deze eenvoud opdelen in drie categorieën: de hoeveelheid opties en verschillen in de structuur van de data, de rijkheid van de data die je wilt aanbieden en tenslotte de indeling van de requests (verzoeken) en responses (ontvangst) binnen de workflow. Er zijn er natuurlijk nog wel meer, maar dit zijn de drie belangrijkste bronnen voor de complexiteit van het systeem

Beperk de opties tot een minimum. Een URL (pad) kan op vele manieren worden opgebouwd en opgedeeld. Een complexe manier zou zijn om bijvoorbeeld een request te doen op een object ‘huis’ waarbij je de ontwikkelaar die jouw systeem gebruikt de mogelijkheid geeft om in de request aan te geven welke data in het huis teruggegeven moet worden. Bijvoorbeeld hoeveel deuren er zijn, of hoeveel muren. Om het tot een minimum te houden kun je beter het object huis terugsturen. Hierdoor kan de data beter worden gecached omdat er minder verschillende paden hoeven worden vastgehouden. Dit verbeterd de prestatie en voorkomt vertragingen.

Verrijkte data, ontstaan uit uitgebreide structuur definities of semantisch verbeterde inhoud, zijn goed voor de integratie en het verbeteren van de verwerking van de data. Dit lijkt erg positief voor de ontwikkeling maar helaas voegt dit ook een drempel toe aan de ontwikkelsnelheid. Er zal ook meer ondersteuning nodig zijn van de content-teams. Werk dus samen met je inhoudsexperts om er zeker van te zijn dat de data die je nodig hebt een deel is van het systeem en niet een verrijking toegevoegd door de API.

Voor de laatste stap, de indeling van de verzoek- en ontvangspatronen (requests en responses) moet je jezelf de vraag stellen of de workflows eenvoudig zijn. De verificatie voor het maken van een betaling of het inloggen op een beveiligd gedeelte bestaat vaak uit een aantal complexe stappen. Meerdere stappen kunnen op meerder momenten voor fouten zorgen.

Wanneer je gebruik maakt van publieke standaarden zullen deze je helpen een eenvoudige integratie te realiseren. De bugs of veiligheidsfouten zullen tot een minimum worden beperkt. Gebruik standaarden en ga alleen bij hoge uitzondering zelf aan de gang.

2. Standaarden

Standaarden zijn er om gehanteerd te worden. Zorg ervoor dat de data die je teruggeeft voldoet aan het gekozen formaat. Hierdoor kan een ontwikkelaar hier snel mee aan de slag.

Hoogstwaarschijnlijk wil je een API maken dat ReSTful is. Je zult de correcte HTTP methoden gebruiken voor acties en paden. Wanneer je in dit geval in het pad de woorden ‘save’, ‘create’, ‘read’ tegenkomt gaat er iets fout. In de ReSTful standaarden staat dat deze acties gelijk duidelijk moeten zijn. Wanneer een request ReSTful is wordt bijvoorbeeld een alleen een type en een ID meegegeven. Alleen het type om een lijst op te halen, een ID om de detailpagina op te halen.

3. Consistente en intuitieve naamgeving

De woorden, labels en meervoudsvormen moeten consistent zijn. Zorg ervoor dat deze niet teveel op elkaar lijken om verwarring te voorkomen. Wanneer dit het geval is zal een ontwikkelaar de functionaliteit beter onthouden en gemakkelijker op hun intuitie afgaan. Het documenteren is op deze manier ook een stuk eenvoudiger en vooral sneller. Meer tijd voor ontwikkeling dus!

4. Correcte codes

Iedere response, moet een correcte HTTP status code hebben. Deze worden vaak vergeten maar zijn vooral belangrijk om ontwikkelaars te helpen met het debuggen van hun code.

In tegenstelling tot websites, welke vaak maar een klein aantal van deze codes hebben, heeft een Web API er meer. Bij een website is een bericht op de pagina informatief voor de gebruiker. Bij een Web API is een stuk meer informatie te verkrijgen uit een HTTP status code.

Sommige applicaties maken gebruik van zelf gedefinieerde codes of passen bestaande codes aan voor eigen gebruik. Een voorbeeld hierin is Twitter die code 429 aanmaakte. Ze gebruiken deze code om een ‘Too Many Requests’ af te vangen. Dit is een aanpassing aan de ‘Verzoek Afgewezen’ code en wordt gebruikt wanneer een verzoek de limiet heeft bereikt. Het verzoek wordt afgewezen omdat de server een cool-down nodig heeft.

Het verwijderen wordt vaak onderverdeeld in verschillende codes. Een code 200, OK, om te melden dat het item succesvol verwijderd is. Een 204 dat aangeeft dat er niets is om te verwijderen. Een 403 wanneer je geen toestemming hebt om te verwijderen. Een 404 wanneer het te verwijderen item niet is gevonden. Een 410 voor wanneer de content niet gevonden is en verwacht wordt dat de content ook niet gevonden zal worden.

Voorbeelden van deze codes;

  1. Vraag een item op met een GET verzoek; 200 OK
  2. Maak een item aan met een POST actie; 201 Created
  3. Fout in de opmaak van het verzoek; 400 Bad Request
  4. Verzoek met authenticatie fout; 401 Unauthorized

Deze codes zijn op zichzelf informatief, maar een omschrijving voor wat er precies fout gaat is nóg informatiever. Je zou zelfs een link naar de documentatiepagina kunnen toevoegen.

Een voorbeeld wanneer geen omschrijving gegeven wordt is de ‘Something went wrong’. Formulieren geven wel eens deze melding wanneer er een fout aanwezig is.De ontwikkelaar krijgt verder geen verklaring van wat er fout is gegaan. Dit kan tot flinke frustatie leiden.

5. Cache richtlijnen

Caching is erg belangrijk. Web systemen en browsers letten hier zorgvuldig op. Caching bepaald wanneer data opnieuw moet worden ingeladen. Zo niet, dan kan de data worden vastgehouden om snelheid te optimaliseren (https://developers.google.com/speed/docs/insights/
LeverageBrowserCaching).

Er moeten eigen regels aangehouden worden die gebruik maken van de correcte HTTP caching headers. Deze caching voor bijvoorbeeld proxies en browsers zorgt ervoor dat de applicatie zo soepel mogelijk werkt door de verzoeken tot een minimum te houden.

Geef altijd een maximum tijd mee om de inhoud te cachen maar zorg ervoor dat deze reëel is. Wanneer je deze op een week zet kan dat gevolgen hebben op de versheid van de inhoud.

6. Zichtbaarheid

Heeft je API een duidelijke documentatie voor nieuwe ontwikkelaars? Zijn de paden netjes en zijn er links naar gerelateerde inhoud binnen de documentatie? Links naar de auteur en revisie informatie zijn ook erg handig om te hebben.

Het ontwikkelen van een design is een flexibele discipline. Je hebt de mogelijkheid om duidelijke pointers te geven in de responses en kan de ontwikkelaar duidelijke informeren over wat ze moeten weten. Dit is een groot en krachtig voordeel voor de ontwikkelaar.

Een goede manier om te testen of de documentatie duidelijk genoeg is is om iemand met minder kennis van zaken een van de paden binnen het systeem te geven. Kijk of ze een successvol verzoek kunnen maken. Kijk of ze de documentatie lezen en begrijpen. Mogelijk bloggen ze wel over wat ze geleerd hebben van de applicatie.

7. Kennis van zaken

Wanneer je een API bouwt op een uitgebreid systeem met veel functionaliteit is het eenvoudig de gemakkelijke weg te kiezen. Je past gewoon de core variabelen aan, zet dit om naar JSON formaat en stuurt deze data op. Dit is een slechte eigenschap omdat het kan zijn dat deze niet relevant of verwarrend zijn voor een ontwikkelaar.

Wanneer je de Drupal structuur neemt kan de ontwikkelaar zich afvragen waar ‘nid’ of ‘vid’ voor staat. Of waarom sommige eigenschappen beginnen met ‘field_’ en anderen niet.

Voor een Drupal ontwikkelaar zijn deze gegevens vrij duidelijk maar een ontwikkelaar zonder Drupal kennis moet hier ook mee overweg kunnen.

8. Uitbreidbaarheid

Wanneer systemen worden uitgebreid moeten de oudere versies blijven werken, dit is wanneer we spreken van ‘backward compatibility’. Er is ook ‘forward compatibility’, het voorzien en anticiperen op mogelijke aanpassingen en/of toevoegingen in de toekomst.

Hiervoor is het verstandig om de plannen meteen in het design vast te zetten. Je kunt er het beste alvast rekening mee houden dat een gebruiker begint met éen telefoonnummer maar in de toekomst mogelijk meerdere nummers wil opslaan. In dit geval zou ‘phone_numbers’ een logischere keuze zijn dan ‘phone_number’.

9. Complete documentatie

Is het implementeren voor anderen eenvoudig genoeg? Kan het zonder dat er uitgebreide vragen gesteld hoeven te worden? De documentatie is niet uitgebreid genoeg wanneer dit niet het geval is. Gelukkig zijn er hulpmiddelen zoals Swagger, RAML of Blueprint voor het maken van duidelijke documentatie.

Voor complexere workflows zoals het gebruik van oAuth is het aan te raden om sequence diagrammen te gebruiken.
Hierin kan je de complete flow van requests en responses documenteren.

10. Uitvoerig en vooral kritisch testen

De documentatie moet duidelijk alle details weergeven. Anderen moeten de implementatie kunnen begrijpen. Ook moeten de limieten duidelijk zijn. Zo kan het bijvoorbeeld zijn dat een verzoek afhangt van bevestiging in de database. Kan het systeem honderden dan wel duizenden verzoeken per dag aan?

Dit moet uitvoerig worden getest maar kan ook door anderen worden aangegeven.

Voorbeelden

Zelfs als je een complete documentatie hebt gemaakt van je Web API kan het verwarrend zijn voor mensen met weinig verstand van zaken. Het is dan ook erg handig om live voorbeelden te geven op een demonstratieomgeving.

 

Comments

Nóg meer
kennis nodig?

Check ons ons blog archief >