API-design

Från krav till ett API

Liksom de flesta tekniker är ett API en lösning på ett problem. För att designa rätt API måste du se till att problemet du adresserar är tydligt definierat genom att svara på följande frågor:

• Vilka är målkonsumenterna för detta API?
• Vilken typ av information kommer konsumenterna att manipulera via API:et?
• Vilka åtgärder kommer konsumenterna att utföra på API:et?

Till exempel, om du är ett matleveransföretag, kanske du vill bygga ett API för ditt partnernätverk som gör det möjligt för dem att bläddra och söka i en databas med restauranger som du tillhandahåller en leveranstjänst för.

I det här exemplet riktar sig ditt API till partners till ditt företag. De kommer att behöva manipulera data om restauranger och utföra sökfrågor på data, med vissa filtrerings- och sorteringsfunktioner.

Ett annat exempel: om du är ett kalender-SaaS-företag, kanske du vill bygga ett API så att andra front-end-utvecklare i världen kan skapa nya mobil- och webbapplikationer baserade på ditt kalendersystem.

Att tänka på konsumenterna av ditt API är det första steget mot att ge dem en bra utvecklarupplevelse. Detta kommer att hjälpa ditt API att sticka ut och öka engagemangsnivåerna.

Elementen som utgör ett API

Det finns fyra nyckelkoncept som används när man designar ett API:

• En Resurs är ett element som dina konsumenter kommer att interagera med via ditt API. Resurser identifieras unikt av en sökväg, som i kombination med API:ets slutpunkt ger en unik adress för en resurs på webben. Till exempel är Calendars namnet på en resurs som motsvarar en lista över kalendrar, och dess sökväg är /calendars.
• En Operation är den åtgärd som kan utföras på dina resurser. De vanligaste operationerna är GET (läs), POST (skapa), PUT (uppdatera) och DELETE. Till exempel är List all Calendars namnet på en operation som använder GET-metoden på resursen Calendars.
• En Datatyp är en beskrivning av de faktiska data som utbyts över nätverket. Till exempel är Calendar namnet på en datatyp som kommer att beskriva alla egenskaper för en kalender, såsom dess namn, ägare och en referens till de händelser som tillhör den. Operationen List all Calendars returnerar en lista med Calendar-datatyper.
• En Komponent är ett element som kan återanvändas i hela API-definitionen. Till exempel, om du behöver använda samma frågeparameter i flera operationer, kan du skapa den som en komponent och referera till den i så många operationer som behövs.

Det finns andra användbara element som utgör ett API:

• En Slutpunkt är den huvudsakliga ingångspunkten för ditt API på webben. En slutpunkt består av ett schema som HTTPS och en värd som www.calendar-api.com.
• Ett Text-block kan användas för att fritt ange valfri text (inklusive markdown) som kan placeras var som helst i din API-design. Använd textblock för att förklara övergripande ämnen som autentisering och felhantering.
• Ett Delavsnitt används för att på ett meningsfullt sätt gruppera resurser och datatyper. Använd dessa för att göra din API-design tydligare och mer utvecklarvänlig. Du kan använda dra och släpp för element i delavsnitt i den vänstra panelen, och du kan också ändra ordning på delavsnitt sinsemellan.

I API Designer kommer du att kunna skapa dessa element från menyn Skapa ny i det övre högra hörnet.

Server-URL:er skapas på skärmen för allmän information. En server-URL kan vara Publicerad eller Inte publicerad. Om den är publicerad visas den i Live-dokumentationen.