De basisprincipes van REST en RESTful API Development

Webontwikkelaars praten vaak over REST-principes en RESTful data-architectuur, omdat het een cruciaal aspect is van moderne ontwikkeling, maar soms kan het ongelooflijk verwarrend zijn. REST is geen technologie op zich, maar eerder een methode voor het maken van API's met bepaalde organisatieprincipes . Deze principes zijn bedoeld om ontwikkelaars te begeleiden en een meer universele omgeving te creëren voor het verwerken van API-aanvragen.

In deze post wil ik RESTful ontwikkelingspraktijken vanuit een vogelvluchtperspectief toelichten. Ik wil het wat aanpakken in plaats van het hoe . Hoewel ik het op beide gebieden zal aanraken, is dit bericht gemaakt voor iedereen die zich bezig houdt met webontwikkeling, maar het concept van REST-API's gewoon niet begrijpt.

REST Voor webontwikkelaars

Het acroniem REST staat voor Representational State Transfer . Dit klinkt misschien wat verwarrend, en de wiki-invoer maakt het nog verwarder. Maar het is mogelijk om de terminologie te vereenvoudigen.

REST is slechts een reeks richtlijnen en architecturale stijlen die worden gebruikt voor gegevensoverdracht . Het wordt vaak toegepast op webapplicaties, maar kan ook gegevens doorgeven aan software.

De acronym API staat voor Application Programming Interface, wat methoden zijn om verbinding te maken met andere bibliotheken of applicaties . Windows heeft meerdere API's en Twitter heeft ook een web-API, hoewel ze verschillende taken met verschillende doelen uitvoeren.

Alles bij elkaar combineren RESTful API's zijn API's die de REST-architectuur volgen.

Wat is de REST-architectuur precies?

Dit is waar het moeilijk is om details vast te leggen. Er zijn echter enkele architectonische constanten, zoals:

• Consistentie voor de gehele API
• Staatloos bestaan, dwz geen sessies aan de serverzijde
• Gebruik van HTTP-statuscodes waar van toepassing
• Gebruik van URL-eindpunten met een logische hiërarchie
• Versiebeheer in de URL in plaats van in HTTP-headers

Er zijn geen overdreven specifieke richtlijnen zoals de W3C HTML5-specificatie die tot verwarring zou kunnen leiden, en een miasma van onzekerheid rond REST-terminologie.

De bovenstaande lijst moet ook niet worden beschouwd als hard-en-snel regels, ook al zijn ze waar voor de meeste moderne RESTful API's.

REST is een lichtgewicht methodologie die het perfect maakt voor HTTP-gegevens. Dit is de reden waarom REST zo populair is geworden op het web en daarom algemeen wordt beschouwd als de beste keuze voor API-ontwikkeling.

Zoals Vinay Sahni het stelt: "een API is de gebruikersinterface van een ontwikkelaar." Alles moet gemakkelijk te gebruiken zijn en een geweldige gebruikerservaring bieden. RESTful API's proberen precies dat te doen.

Key Takeaways voor RESTful API's

Deze tips zijn in de context van API's uitsluitend voor webtoepassingen . Dit betekent dat HTTP een vereiste is en dat dit vaak betekent dat de API-gegevens worden gehost op een externe server . Laten we eens kijken hoe RESTful API's aan de kant van de API-gebruiker werken.

De API-gebruiker is de webontwikkelaar die een script kan bouwen dat verbinding maakt met een externe API-server, waarna de benodigde gegevens worden doorgegeven via HTTP. De ontwikkelaar kan vervolgens gegevens op hun website weergeven zonder persoonlijke toegang tot de externe server te hebben (zoals Twitter-gegevens te trekken).

Over het algemeen zijn er vier opdrachten die worden gebruikt om toegang te krijgen tot RESTful API's :

1. GET voor het ophalen van een object
2. POST voor het maken van een nieuw object
3. PUT voor het wijzigen of vervangen van een object
4. DELETE voor het verwijderen van een object

Elk van deze methoden moet worden doorgegeven met de API-aanroep om de server te vertellen wat te doen.

Het overgrote deel van de web-API's staan alleen toe dat GET aanvragen gegevens ophalen van een externe server. Verificatie is optioneel, maar is zeker een goed idee bij het toestaan ​​van mogelijk schadelijke opdrachten zoals PUT of DELETE .

Maar niet veel RESTful API's gaan zelfs zover. Overweeg Pokéapi, een gratis API-database voor Pokémon. Het is open voor het publiek met fatsoenlijke snelheidsbeperking (het beperken van gebruikers tot een bepaald aantal API-verzoeken gedurende een bepaalde periode), maar staat alleen de GET methode toe voor toegang tot bronnen. Dit kan in de volksmond een API voor alleen consumptie worden genoemd.

Retoursoorten zijn ook belangrijk en moeten homogeniteit behouden voor alle bronnen. JSON is een populair retourtype met online specs die de juiste datastructuren uitleggen.

RESTful API's gebruiken zelfstandige naamwoorden voor API-objecten en werkwoorden voor het uitvoeren van acties op die objecten. Authenticatie kan hier onderdeel van zijn, ook hier kan snelheidsbeperking onderdeel van zijn. Maar een zeer eenvoudige API kan langskomen zonder veel zorg te besteden aan gebruikersbeperkingen.

Toegang tot API-bronnen

Openbare API's zijn meestal toegankelijk via directe webadressen . Dit betekent dat de URL-structuur belangrijk is en alleen voor API-verzoeken moet worden gebruikt.

Sommige URL's kunnen een prefixdirectory bevatten zoals /v2/ voor een bijgewerkte versie 2 van een vorige API. Dit is gebruikelijk voor ontwikkelaars die hun 1.x API niet willen depreciëren, maar toch de nieuwste structuur willen aanbieden.

Ik heb echt genoten van dit bericht over basis-URL-structuren en voorbeelden van andere services.

Merk op dat de retourgegevens van het eindpunt drastisch zullen veranderen op basis van de HTTP-methode . GET haalt bijvoorbeeld inhoud op, terwijl POST nieuwe inhoud maakt. Het verzoek zou naar hetzelfde eindpunt kunnen verwijzen, maar het resultaat zou heel anders kunnen zijn.

Door online voorbeelden te bekijken, kunt u concepten beter begrijpen. We hebben de Pokeapi al gezien, maar hier zijn enkele andere real-world API-voorbeelden om te lezen:

• Reddit API
• GitHub API
• Flickr API
• Pinterest API

Uw eigen API bouwen

Het proces van het bouwen van uw eigen API moet niet lichtvaardig worden genomen, maar het is ook niet zo ingewikkeld als u misschien denkt. Het heeft wel inzicht nodig in API-ontwerppatronen en beste praktijken om iets van echte waarde te bouwen.

Elke API moet verbinding maken met uw server om gegevens van een of andere soort terug te sturen. U hoeft niet alleen code te schrijven om dat te doen, maar u moet ook de retourgegevens opmaken. Andere mogelijke vereisten zijn authenticatie en snelheidsbeperking, dus het bouwen van een API is zeker niet voor bangeriken.

Maar laten we eens kijken naar enkele basisprincipes van API-architectuur.

Bouw eindpunten

Een aspect van API-ontwikkeling is het bouwen van eindpunten . Bij het maken van bronnen wilt u zelfstandige naamwoorden gebruiken, geen werkwoorden. Dit betekent dat API-gegevens een persoon, plaats of ding moeten teruggeven, meestal is het een ding met specifieke kenmerken (bijvoorbeeld een tweet en al zijn metadata).

Het kan moeilijk zijn om zelfstandige naamwoorden te leren, maar dit is een cruciaal aspect van API-ontwikkeling. Vereenvoudiging is het beste waar mogelijk.

Een groot debat is enkelvoud versus meervoud . Als u een Twitter API aan het maken bent, kunt u de objectgroep eerst hebben (tweet) en vervolgens het objectitem als tweede (tweet ID).

 $ / tweet / 15032934882934 $ / tweets / 15032934882934 

In dit geval zou ik zeggen dat de enkelvorm er beter uitziet. Dit is met name het geval wanneer slechts één bron wordt geretourneerd. Maar er is geen gedocumenteerd 100% correct antwoord, dus doe wat het beste past bij uw project.

Stel Return Type in

Een andere overweging zijn gegevens van het retoursoort . De meeste webgebruikers verwachten JSON-inhoud, dus dat is waarschijnlijk de beste optie. XML is een andere keuze als u beide wilt aanbieden. JSON is echter het fundamentele API-retourtype bij webontwikkelaars.

Er is veel meer in de ontwikkeling van API's, dus ik raad aan eerst met API's te spelen. Op deze manier kunt u zien hoe andere ontwikkelaars hun API's bouwen en hopelijk zult u bekend raken met de typische vereisten.

Als je net begint, overweeg dan om deze dev-tutorials te skimmen:

• REST API zelfstudie site
• Een eenvoudige REST-API schrijven
• Een RESTful Web Service bouwen

Verdere bronnen

De beste manier om de ontwikkeling van webapp te leren, is door te oefenen. Toegegeven theorie is altijd het bestuderen waard, omdat je hiermee met ontwikkelaars kunt praten en begrijpen hoe de dingen werken.

Maar een goede plek om met API-ontwikkeling te beginnen, is eerst verbinding maken met andere API's . Leer de basisprincipes van client-side verbindingen, en vanaf daar kunt u overstappen naar server-side API-ontwikkeling door vanuit het niets uw eigen API te creëren.

Als dat je doel is, overweeg dan de volgende bronnen om je te helpen tijdens je reis.

Boeken

• REST API Design Rulebook
• RESTful Web API's
• RESTful Web Services Cookbook
• Ongestoord REST: een gids voor het ontwerpen van de perfecte API

artikelen

• Een beginnershandleiding voor HTTP en REST
• Een RESTful API maken
• RESTful Resource Naming Guide
• Een REST API maken met behulp van de MEAN-stack