API-ontwerp

Van vereisten naar een API

Zoals 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 doelconsumenten 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 misschien een API bouwen voor uw partnernetwerk waarmee zij kunnen bladeren en zoeken in een database van restaurants waarvoor u een bezorgservice biedt.

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

Nog een voorbeeld: als u een agenda-SaaS-bedrijf bent, wilt u misschien een API bouwen zodat andere front-end ontwikkelaars in de 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 verhoogt de betrokkenheid.

De elementen waaruit een API bestaat

Er worden vier sleutelconcepten gebruikt bij het ontwerpen van een API:

• Een Resource is een element waarmee uw consumenten zullen communiceren 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 is /calendars.
• Een Bewerking is de actie die kan worden uitgevoerd op uw resources. De meest voorkomende bewerkingen zijn GET (lezen), POST (maken), PUT (bijwerken) en DELETE. List all Calendars is bijvoorbeeld de naam van een bewerking die de GET-methode gebruikt op de resource Calendars.
• Een Gegevenstype is een beschrijving van de daadwerkelijke gegevens die via het netwerk worden uitgewisseld. Calendar is bijvoorbeeld de naam van een gegevenstype dat alle eigenschappen van een agenda 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 verschillende bewerkingen moet gebruiken, kunt u deze als een component maken en ernaar verwijzen in zoveel bewerkingen als nodig is.

Er zijn andere nuttige elementen waaruit een API bestaat:

• Een Eindpunt 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 in te voeren (inclusief markdown) 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 op een zinvolle manier te groeperen. Gebruik deze om uw API-ontwerp duidelijker en gebruiksvriendelijker voor ontwikkelaars te maken. U kunt elementen naar secties in het linkerdeelvenster slepen en neerzetten, en u kunt secties ook onderling opnieuw ordenen.

In API Designer kunt u deze elementen maken via het menu Nieuwe maken in de rechterbovenhoek.

Server-URL's worden gemaakt in het scherm met algemene informatie. Een server-URL kan Gepubliceerd of Niet gepubliceerd zijn. Als deze is gepubliceerd, verschijnt deze in de Live Documentation.