9 trendy best practices voor
REST API-ontwikkeling
Facebook, GitHub, Netflix en andere vooraanstaande technologische bedrijven hebben ontwikkelaars uitgenodigd om hun gegevens te benutten via API's. Het is een trend voor innovatieve tech-platforms om hun infrastructuur te versterken met zorgvuldig samengestelde REST API's.
Een goed ontworpen REST API
Een API fungeert als reflecterende interface waarmee ontwikkelaars communiceren met gegevens. Met de ondersteuning van een doordacht gestructureerde en ontworpen API kan gemak en efficiëntie worden geïntegreerd in het leven van ontwikkelaars. De cruciale factor hierbij is een goed ontworpen REST API. Als de REST API niet foutloos is ontworpen, kan dit problemen opleveren voor ontwikkelaars, eerder dan het verbeteren van de gebruikerservaring. Het is dan ook van belang om de gangbare conventies voor API-ontwerp te volgen om de optimale oplossing te bieden aan zowel klanten als ontwikkelaars.
Tips voor het ontwerpen van REST API's
1. REST API moet JSON accepteren en reageren
Het is gebruikelijk dat API’s JSON-verzoeken als playload moeten accepteren en ook reacties terug moeten sturen in JSON-formaat. JSON is een open en gestandaardiseerd formaat voor gegevensoverdracht, afgeleid van JavaScript om op een eenvoudige manier JSON te encoderen en decoderen via de Fetch API of een andere HTTP-client. Bovendien hebben server-side technologieën bibliotheken die JSON probleemloos kunnen decoderen.
Laten we kijken naar een voorbeeld van een API waar JSON-playloads worden geaccepteerd. Een screenshot van Postman om JSON naar onze API te sturen.
2. Gebruik ERROR statuscodes
HTTP heeft al meer dan 100 statuscodes ingebouwd. Het is een zegen voor ontwikkelaars om statuscodes te gebruiken in hun REST API-ontwerp. Met behulp van de statuscodes kunnen ontwikkelaars direct het probleem identificeren, wat de tijd voor het schrijven van parsers om verschillende soorten fouten aan te pakken, vermindert. Er is een statuscode voor alles – van het achterhalen van de oorzaak van een afgewezen sessie tot het lokaliseren van ontbrekende bronnen. Ontwikkelaars kunnen snel routines implementeren voor het beheren van talrijke fouten op basis van statuscodes.
3. Gebruik geen werkwoorden in URL’s
Als je de basisprincipes van API’s begrijpt, weet je dat het invoegen van werkwoorden in de URL geen goed idee is. De reden hiervoor is dat HTTP zelfvoorzienend moet zijn om het doel van de actie te beschrijven. Laten we een voorbeeld nemen waarbij je een eindpunt wilt om een bannerbeeld voor een bericht te genereren; je moet opmerken dat de :param en plekhouder is voor een URI-parameter. Je eerste neiging zou kunnen zijn om dit eindpunt te creëren:
GET: /articles/:slug/generateBanner/
De GET-methode geeft hier alleen aan dat je een banner wilt ophalen. Dus, het gebruik van deze syntaxis kan voordelig zijn:
GET: /articles/:slug/banner/
Op dezelfde manier, voor het eindpunt dat mogelijk het nieuwe artikel genereert, zoals getoond in dit voorbeeld.
Gebruik niet:
POST: /articles/createNewArticle/
Gebruik:
POST: /articles/
4. Gebruik meervoudsvormen van zelfstandige naamwoorden voor de naamgeving van een collectie
Bij het ontwikkelen van een verzameling in een REST API, kies gewoon voor de meervoudsvorm van zelfstandige naamwoorden. Dit maakt het gemakkelijker voor mensen om de betekenis van de verzameling te begrijpen zonder deze daadwerkelijk te openen. Laten we dit voorbeeld nemen:
GET /cars/123
POST /cars
GET /cars
Het is duidelijk uit het voorbeeld dat ‘auto’ wordt aangeduid als nummer 123 in de hele lijst van ‘auto’s’. Het gebruik van een meervoudig zelfstandig naamwoord geeft eenvoudigweg aan dat dit een verzameling verschillende auto’s is. Kijk nu naar een ander voorbeeld:
GET /car/123
POST /car
GET /car
Dit voorbeeld geeft niet duidelijk aan of er meer dan één auto in het systeem is of niet. Voor een menselijke lezer kan het ook lastig zijn om te begrijpen.
5. Goed samengestelde documentatie
Documentatie is een van de belangrijke maar vaak genegeerde aspecten van een REST API-structuur. De documentatie is het eerste wat klanten in handen hebben om het product te begrijpen, en het is een cruciale beslissende factor of ze het al dan niet zullen gebruiken. Goede documentatie is overzichtelijk gepresenteerd in een logische volgorde om het API-ontwikkelingsproces te versnellen.
Het is een eenvoudig principe: hoe sneller ontwikkelaars de API begrijpen, hoe sneller ze het gaan gebruiken. De API-documentatie moet met precisie zijn samengesteld. Het moet alle relevante informatie bevatten, zoals eindpunt- en compatibele methoden, verschillende parameteropties, diverse soorten gegevens, etc. De documentatie moet zo robuust zijn dat het een nieuwe gebruiker gemakkelijk door het API-ontwerp kan leiden.
6. Geef foutdetails terug in het antwoordlichaam
Het is handig voor het API-eindpunt om foutdetails terug te geven in de JSON of het antwoordlichaam om een gebruiker te helpen bij het debuggen. Als je expliciet het getroffen veld in de fout kunt opnemen, verdien je daarbij speciale waardering.
7. Gebruik resource-nesting
Resource-doelstellingen bevatten altijd een soort functionele hiërarchie of zijn met elkaar verbonden. Het is echter nog steeds ideaal om de nesting in de REST API te beperken tot één niveau. Te veel geneste niveaus kunnen hun elegante uitstraling verliezen. Als we het voorbeeld van de online winkel in overweging nemen, zien we dat "gebruikers" en "bestellingen" deel uitmaken van winkels. Bestellingen behoren tot een bepaalde gebruiker; daarom ziet de eindpuntstructuur er als volgt uit:
/users // list all users
/users/123 // specific user
/users/123/orders // list of orders that belong to a specific user
/users/123/orders/0001 // specific order of a specific users order list
8. Gebruik SSL/TLS
Wanneer je de communicatie met je API moet versleutelen, gebruik dan altijd SSL/TLS. Maak gebruik van deze functie zonder verdere vragen.
9. Beveilig je API
Het is een favoriete bezigheid voor hackers om geautomatiseerde scripts te gebruiken om je API-server aan te vallen. Daarom moet je API proactieve beveiligingsmaatregelen volgen om operaties uit te voeren terwijl je gevoelige gegevens soepel beschermt. Ten eerste moet je API een HTTP Strict Transport Security (HSTS)-beleid hebben. Vervolgens moet je je netwerk beveiligen tegen aanvallen van tussenpersonen, aanvallen op protocolafwaardering, sessieovername, enzovoort. Gebruik gewoon alle relevante beveiligingsstandaarden voor de beveiliging van je API.
Een perfect ontworpen REST API blijft aan de positieve kant van technische beperkingen en biedt oplossingen op basis van gebruikerservaring. Een API maakt deel uit van de bedrijfsstrategie; het is een marketinginstrument voor de organisatie, daarom is het essentieel om API's op de juiste manier uit te voeren. Dat komt omdat een ongestructureerde API eerder een aansprakelijkheid dan een aanwinst is.
Neem contact op voor meer informatie of laat een berichtje achter. We helpen graag!