API-design

Gå från krav till ett API

Precis som de flesta tekniker är ett API en lösning på ett problem. För att designa rätt API behöver du se till att problemet du adresserar är tydligt definierat genom att besvara följande frågor:

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

Om du till exempel ä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 partner till ditt företag. De kommer att behöva manipulera data om restauranger och utföra sökfrågor mot datan, med vissa filtrerings- och sorteringsfunktioner.

Ett annat exempel: om du är ett kalender-SaaS-företag vill du kanske bygga ett API så att andra frontend-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.

De element som utgör ett API

Det finns fyra nyckelbegrepp 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, vilket 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äsa), 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 beskriver alla egenskaper hos en kalender, såsom dess namn, ägare och en referens till de händelser som tillhör den. Åtgärden List all Calendars returnerar en lista över Calendar-datatyper.
• En komponent är ett element som kan återanvändas i hela API-definitionen. Om du till exempel 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. An slutpunkt består av ett schema såsom HTTPS och en värd så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.
• En sektion används för att gruppera resurser och datatyper på ett meningsfullt sätt. Använd dessa för att göra din API-design tydligare och mer utvecklarvänlig. Du kan dra och släppa element till sektioner i den vänstra panelen, och du kan även ordna om sektionerna inbördes.

I API-kontrakt 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 Documentation.