API ontwerpen

Van vereisten naar een API

Net als de meeste technologieën is een API een oplossing voor een probleem. Om de juiste API te ontwerpen, moet u ervoor zorgen dat het probleem dat u aanpakt duidelijk is gedefinieerd door de volgende vragen te beantwoorden:

• Wie zijn de beoogde consumenten van deze API?
• Wat voor soort informatie zullen consumenten via de API manipuleren?
• Welke acties zullen consumenten uitvoeren op de API?

Als u bijvoorbeeld een maaltijdbezorgbedrijf bent, wilt u wellicht een API bouwen voor uw partnernetwerk waarmee zij kunnen bladeren en zoeken in een database van restaurants waarvoor u een bezorgdienst aanbiedt.

In dit voorbeeld richt uw API zich op partners van uw bedrijf. Ze moeten gegevens over restaurants manipuleren en zoekopdrachten uitvoeren op de gegevens, met bepaalde filter- en sorteermogelijkheden.

Een ander voorbeeld: als u een agenda-SaaS-bedrijf bent, wilt u wellicht een API bouwen zodat andere frontend-ontwikkelaars over de hele wereld nieuwe mobiele en webapplicaties kunnen maken op basis van uw agendasysteem.

Nadenken over de consumenten van uw API is de eerste stap om hen een goede ontwikkelaarservaring te bieden. Dit helpt uw API op te vallen en de betrokkenheid te vergroten.

De elementen waaruit een API bestaat

Er zijn vier kernconcepten die worden gebruikt bij het ontwerpen van een API:

• Een Resource is een element waarmee uw consumenten interactie hebben via uw API. Resources worden uniek geïdentificeerd door een pad, dat in combinatie met het eindpunt van de API een uniek adres biedt voor een resource op het web. Calendars is bijvoorbeeld de naam van een resource die overeenkomt met een lijst met agenda's, en het pad ervan is /calendars.
• Een bewerking is de actie die kan worden uitgevoerd op uw resources. De meest voorkomende bewerkingen zijn GET (lezen), POST (aanmaken), PUT (bijwerken) en DELETE. List all Calendars is bijvoorbeeld de naam van een bewerking die gebruikmaakt van de GET-methode op de Calendars-resource.
• Een datatype is een beschrijving van de daadwerkelijke gegevens die via het netwerk worden uitgewisseld. Calendar is bijvoorbeeld de naam van een datatype dat alle eigenschappen van een kalender beschrijft, zoals de naam, de eigenaar en een verwijzing naar de gebeurtenissen die erbij horen. De bewerking List all Calendars retourneert een lijst met Calendar-gegevenstypen.
• Een Component is een element dat in de hele API-definitie kan worden hergebruikt. Als u bijvoorbeeld dezelfde queryparameter in meerdere bewerkingen moet gebruiken, kunt u deze als component aanmaken en ernaar verwijzen in zoveel bewerkingen als nodig is.

Er zijn andere nuttige elementen waaruit een API bestaat:

• Een Endpoint is het belangrijkste toegangspunt voor uw API op het web. Een eindpunt bestaat uit een schema zoals HTTPS en een host zoals www.calendar-api.com.
• Een Tekst-blok kan worden gebruikt om vrijelijk tekst (inclusief markdown) in te voeren die overal in uw API-ontwerp kan worden geplaatst. Gebruik tekstblokken om transversale onderwerpen zoals authenticatie en foutafhandeling uit te leggen.
• Een sectie wordt gebruikt om resources en gegevenstypen zinvol te groeperen. Gebruik deze om je API-ontwerp duidelijker en ontwikkelaarsvriendelijker te maken. U kunt elementen naar secties in het linkerpaneel slepen en neerzetten, en u kunt secties ook onderling opnieuw ordenen.

In API-contracten kunt u deze elementen aanmaken via het menu Nieuw maken in de rechterbovenhoek.

Server-URL's worden aangemaakt in het algemene informatiescherm. Een server-URL kan Gepubliceerd of Niet gepubliceerd zijn. Als het is gepubliceerd, verschijnt het in de Live Documentation.