Hoe ontwerp je een API

Zoals altijd is de context waarin een API wordt gebruikt erg belangrijk. Stel je wilt een systeem operaties laten uitvoeren door een machine. Deze operaties moeten één voor één worden uitgevoerd. De verzameling beschikbare operaties wordt regelmatig uitgebreid.

Het is dan in eerste instantie aantrekkelijk om voor iedere operatie een eigen URL beschikbaar te stellen. Daarmee is de API duidelijk uit te leggen en te voorzien van documentatie per operatie. Als je echter steeds meer operaties toevoegd, dan wordt dit een tijdrovende klus.

Ook hier zal het in eerste instantie wel meevallen, totdat de verzameling operaties groot wordt en er veel checks moeten worden toegevoegd aan iedere operatie. Denk in dit geval aan de check of een operatie al kan worden uitgevoerd of dat er nog een operatie bezig is. Denk ook aan het claimen van de positie in de operationqueue, zodat iedere operatie één voor één zal worden uitgevoerd. Maar ook het vrijgeven van de machine voor een volgende operatie moet worden gedaan.

En dan hebben wij het nog niet eens over de API-consumer die ook voor iedere operatie moet worden aangepast.

Operation queue

In deze situatie is het slimmer om één functie te hebben die alle (of in ieder geval een groot deel van de) operaties kan uitvoeren. Op die manier is er een beperkt deel management-code dat getest en beheerd moet worden.

Verschuiving van complexiteit

Met een operation queue wordt de complexiteit verschoven naar het interne deel van de API-provider (maar natuurlijk ook intern in de API consumer). Als je dit echter slim opbouwt, dan zou je operaties via een database kunnen laten configureren. Daarmee breng je de complexiteit buiten je code en zet je dit om in records of documents in een database systeem.