5 stappen om een ​​succesvolle API te maken

Het is de aard van softwareontwikkeling. Ontwikkelaars maken software met de eindgebruiker in gedachten. Het lijkt vrij eenvoudig, maar soms zijn die gebruikers ook collega-ontwikkelaars. Ze hebben geen dingen nodig die voor hen zijn afgebroken. Ze hebben zelfs de eenvoud niet nodig. Alles wat ze willen is toegang - een manier om uw software met die van hen te integreren. Hier komt een API (applicatie-programmeerinterface) binnen. Ik hoop vijf stappen te markeren die u kunt nemen om een ​​succesvolle API te maken.

Doe je huiswerk

Als het gaat om softwareontwikkeling, wil niemand het wiel opnieuw uitvinden. Op dit moment hebben bijna alle grote webbedrijven API's voor hun softwareproducten. Bestudeer deze API's en probeer de verschillende ontwerpbeslissingen te nemen die nodig zijn om ze te maken.

Er zijn veel verschillende technologieën die er zijn, maar de meeste API's die u zult zien, zullen een RESTful-interface of SOAP gebruiken. Als je niet weet welke API-interface je gaat gebruiken, stel ik voor om met een RESTful-aanpak te werken met behulp van het HTTP-protocol. Het is eenvoudiger dan SOAP, het is momenteel populairder en het zal gemakkelijker zijn om aan de slag te gaan wanneer u een webgebaseerd softwareproduct gebruikt.

Wees consistent

Een van de dingen die ontwikkelaars het meest waarderen, is consistentie. Dit omvat onder meer adresseerbaarheid, invoerargumenten, uitvoerindelingen en foutafhandeling.

Wanneer u een RESTful-aanpak gebruikt, zijn er veel verschillende URI-naamgevingsschema's. Elk heeft zijn supporters, dus kies er gewoon een en blijf erbij. Hetzelfde geldt voor invoer- en uitvoerstructuur. De meeste API's ondersteunen het gebruik van XML en JSON als invoer- en uitvoerindelingen. Ik zou willen voorstellen beide te ondersteunen, maar een standaardformaat te kiezen.

Voor invoer moeten uw invoereisen consistent worden genoemd en moeten ze logisch zijn in de context van de API-aanroep die u doet. Zorg er voor uitvoer voor dat u algemene datastructuurlay-outs gebruikt. Als u de uitvoer van één API-aanroep verpakt in a XML-tag, overweeg dat te doen met uw andere oproepen.

Het is gebruikelijk om een ​​soort statusvlag op te nemen in de uitvoergegevens die u terugstuurt naar de client. Bij gebruik van een RESTful API-aanpak moet dit worden gedaan met behulp van HTTP-statuscodes. Als u bijvoorbeeld net een PUT-verzoek voor een bestaand gegevensobject hebt verwerkt, varieert de HTTP-statuscode die u in uw antwoord opneemt, afhankelijk van de uitkomst van het verzoek.

In plaats van een willekeurige vlag die de status van de oproep aangeeft, kan een standaard "200 OK" -statuscode worden gebruikt om aan te geven dat het verzoek is geslaagd, terwijl een statuscode "400 Bad Request" kan worden gebruikt om aan te geven dat het verzoek misvormde. Er zijn nogal wat HTTP-statuscodes die in verschillende situaties kunnen worden gebruikt.

Gebruik OAuth

De meeste softwareproducten vereisen een soort gebruikersauthenticatie om toegang te krijgen tot beschermde bronnen voor die gebruiker. Als het gaat om API's, is het een slechte gewoonte om de klant de gebruikersgegevens te laten verzamelen om naar uw server te verzenden. Dit is waar OAuth binnenkomt.

OAuth biedt veel voordelen ten opzichte van gebruikersnaam / wachtwoordauthenticatie van derden. Bovenal heeft de client nooit toegang tot de inloggegevens van de gebruiker. De gebruiker wordt omgeleid naar uw server wanneer hij of zij zich aanmeldt. Nadat de gebruiker zich op uw site heeft aangemeld, wordt hij of zij teruggestuurd naar de client waar de client een toegangstoken ontvangt voor toekomstige verzoeken om beschermde bronnen.

Een ander belangrijk voordeel van het gebruik van OAuth is de mogelijkheid van de gebruiker om de clienttoegang op elk gewenst moment te annuleren. Als de gebruiker besluit dat ze om welke reden dan ook niet langer willen dat de client toegang heeft tot beschermde bronnen namens hen, gaan ze gewoon naar een interface die u hebt gemaakt en annuleren ze de toegang van de client.

Begin vroeg

Een van de belangrijkste dingen die u kunt doen om uw API tot een succes te maken, is vroeg beginnen. Wanneer u die functie schrijft om een ​​vermelding in uw database te maken, neem dan de extra tijd en schrijf er een API-interface voor.

Schrijf goede documentatie

Niets doodt een API sneller dan het hebben van geen goede documentatie. Hoewel sommige ontwikkelaars een slecht gedocumenteerde API kunnen gebruiken om erachter te komen hoe deze zou moeten werken, zullen de meeste dit niet willen.

U moet elke beschikbare API-oproep documenteren en uw API-oproepen categoriseren op basis van het type gegevens waarop ze reageren. Naast het documenteren van de eindpunten voor de API-aanroepen zelf, moet u systematisch de vereiste en optionele invoerargumenten definiëren, evenals de uitvoergegevensstructuren. Invoerargumenten moeten een standaardwaarde vermelden als die er is, en ook de verwachte gegevensindeling aangeven, zoals een getal of tekenreeks. Ten slotte moet elke API-aanroep een lijst met foutcondities en statuscodes bevatten.

Om uw documentatie af te ronden, moet u een of twee voorbeelden opnemen voor algemene invoer- en uitvoerscenario's voor elke API-aanroep.

API-ontwikkeling: Keep It Simple

Hoewel het lijkt dat het ontwikkelen van een API een gecompliceerde onderneming is, is het idee van een API zelf geen nieuw concept en is er een grote hoeveelheid beschikbare documentatie over elk onderwerp dat we hier hebben besproken. Zorg er gewoon voor dat u goede werkwijzen gebruikt waar u ze kunt vinden en zorg voor een consistente, goed gedocumenteerde interface.