Innehåll
- Gör dina läxor
- Var konsekvent
- Använd OAuth
- Börja tidigt
- Skriv bra dokumentation
- API-utveckling: Keep It Simple
Hämtmat:
Programvaruutvecklare vill ha ett sätt att integrera sin programvara med din - och de vill inte ha saker uppdelade för dem. Det är här ett API kommer in.
Det är typen av programvaruutveckling. Utvecklare skapar programvara med slutanvändaren i åtanke. Det verkar ganska enkelt, men ibland är dessa användare också andra utvecklare. De behöver inte saker uppdelade för dem. De behöver inte ens behöva enkelheten. Allt de vill ha är åtkomst - ett sätt att integrera din programvara med sin. Det är här ett API (applikationsprogrammeringsgränssnitt) kommer in. I den här artikeln hoppas jag kunna lyfta fram fem steg som du kan vidta för att skapa ett framgångsrikt API.Gör dina läxor
När det gäller mjukvaruutveckling vill ingen av oss återuppfinna hjulet. Just nu har nästan alla stora webbföretag API: er för sina mjukvaruprodukter. Studera dessa API: er och försök ta reda på de olika designbesluten som gjordes för att skapa dem.Det finns många olika tekniker där ute, men de flesta API: er kommer att se kommer att använda antingen ett RESTful gränssnitt eller SOAP. Om du är på staketet för vilket API-gränssnitt du ska använda, skulle jag föreslå att du går med en RESTful-metod med HTTP-protokollet. Det är enklare än SOAP, dess för närvarande mer populära, och det kommer att vara lättare att komma igång med när du använder en webbaserad programvaruprodukt.
Var konsekvent
En av de saker som utvecklare uppskattar mest är konsistensen. Detta inkluderar bland annat adresserbarhet, inmatningsargument, utgångsformat och felhantering.När du använder en RESTful-metod finns det många olika URI-namngivningsscheman. Var och en har sina anhängare, så bara välj en och hålla fast vid den. Detsamma gäller ingångs- och utgångsstrukturen. De flesta API: er stöder användning av XML och JSON som input- och outputformat. Jag föreslår att du stöder båda, men väljer ett standardformat.
För inmatning ska dina inmatningskrav namnges konsekvent och bör vara vettiga i det API-samtal som du gör. För utdata, se till att du använder vanliga datastrukturer. Om du lägger in utgången från ett API-samtal i ett
Det är vanligt att inkludera någon form av statusflagg i utgångsdata som du tillbaka till klienten. När du använder en RESTful API-metod bör detta göras med hjälp av HTTP-statuskoder. Om du till exempel bara har behandlat en PUT-förfrågan på ett befintligt dataobjekt kommer HTTP-statuskoden du inkluderar i ditt svar att variera beroende på resultatet av begäran.
I stället för en godtycklig flagga som indikerar samtalets status, kan en standardkod "200 OK" användas för att beteckna att begäran var framgångsrik, medan en "400 dålig begäran" -statuskod kunde användas för att indikera att begäran var malformed. Det finns ganska många HTTP-statuskoder som kan användas i olika situationer.
Använd OAuth
De flesta mjukvaruprodukter kommer att involvera någon form av användarautentisering för att få åtkomst till skyddade resurser för den användaren. När det gäller API: er är det dåligt att ha klienten att samla in användaruppgifterna till din server. Det är här OAuth kommer in.OAuth ger många fördelar jämfört med tredje parts användarnamn / lösenordsautentisering. Framför allt har klienten aldrig tillgång till användarens referenser. Användaren omdirigeras till din server när han eller hon loggar in. När användaren har loggat in på din webbplats omdirigeras han eller hon tillbaka till klienten där klienten kommer att få ett åtkomsttoken att använda i framtida förfrågningar till skyddade resurser.
En annan viktig fördel med att använda OAuth är användarens möjlighet att avbryta klientåtkomst när som helst. Om användaren beslutar att de oavsett anledning inte längre vill att klienten ska kunna få åtkomst till skyddade resurser på deras vägnar går de helt enkelt till ett gränssnitt som du har skapat och avbryter klientens åtkomst.
Börja tidigt
En av de viktigaste sakerna du kan göra för att göra ditt API till en framgång är att börja tidigt. När du skriver den funktionen för att skapa en post i din databas, gå vidare och ta extra tid och skriva ett API-gränssnitt för det.Skriv bra dokumentation
Ingenting dödar ett API snabbare än att inte ha bra dokumentation. Vissa utvecklare kan ta ett dåligt dokumenterat API och ta reda på hur det ska fungera, men de flesta vill inte.Du bör dokumentera varje API-samtal som du har tillgängligt och kategorisera dina API-samtal efter den typ av data de agerar på. Tillsammans med att dokumentera slutpunkterna för själva API-samtalet bör du systematiskt definiera de obligatoriska och valfria inmatningsargumenten såväl som utgångsdatastrukturerna. Ingångsargument bör lista ett standardvärde om det finns ett, och också ange det förväntade dataformatet som ett nummer eller en sträng. Slutligen bör varje API-samtal ha en lista med felvillkor och statuskoder.
För att avsluta dokumentationen måste du inkludera ett eller två exempel för vanliga input- och outputscenarier för varje API-samtal.