Wat is een REST-API?

TransIP stelt domein- en VPS-diensten beschikbaar via een REST API. In dit artikel leggen wij uit wat een REST API is. Meer algemene informatie over API's vind je hier.

Daarnaast geven wij een overzicht van de type requests die je kunt gebruiken met de TransIP REST API en welke responses je daarop kunt krijgen.

REST API

REST (Representational State Transfer) is een stijl van software architecture voor het ontwerp van netwerk applicaties. Het fundamentele concept van een RESTful API is de 'resource'. Alle informatie die benoemd kan worden is een resource: een document, afbeelding, verzameling (collection) van resources, niet-virtueel object (bijvoorbeeld een persoon) etc. REST gebruikt een resource identifier om een resource te identificeren.

De status van een resource op een willekeurig moment heet een 'resource representation' en bevat data, metadata die de data omschrijft en hypermedia links die de clienten helpen om van status te veranderen.

Het data formaat van een 'resource representation' staat bekend als een 'media type' en stelt vast hoe de resource representation verwerkt moet worden. RESTful API's zien er daarom doorgaans uit als hypertext: ieder stukje informatie ziet er uit als een adres, bijvoorbeeld een link met een ID.

Richtlijnen

REST kent zes richtlijnen waar een API aan moet voldoen om 'RESTful' genoemd te mogen worden:

1. Client-server: Door zorgen over de gebruikers-interface te scheiden van de opslag, verbetert de verplaatsbaarheid van de gebruikers-interface over meerdere platforms. De vereenvoudiging van server componenten verbetert schaalbaarheid.
    
2. Stateless: Ieder verzoek (request) van client naar server moet alle nodige informatie bevatten om het verzoek te begrijpen en kan geen gebruik maken van enige opgeslagen context op de server. De sessie status wordt volledig op de client opgeslagen. Informatie over de gebruiker van de API wordt niet opgeslagen op de server.
    
3. Cacheable: Cache-beperkingen vereisen dat de data in een antwoord (response) informatie bevat of de data wel of niet cacheable is. Als een antwoord cacheable is, krijgt de client rechten om het antwoord opnieuw te gebruiken voor latere, soortgelijke verzoeken. Het antwoord zal dan ook een soort versienummer bevatten, zodat de client weet welke versie van de data het al heeft. Dit geld bijvoorbeeld voor het array dat je terug krijgt bij het opvragen van de specificaties van een VPS met onze REST API.
    
4. Uniform interface: De systeem architectuur wordt vereenvoudigd en de zichtbaarheid van interacties verbeterd, door algemeenheid toe te passen op de component interface. Om een dergelijke uniforme interface te bereiken, zijn vier architecturele beperkingen nodig om het gedrag van componenten vast te leggen:
   • Identificatie van resources
   • Manipulatie van resources door representations (zie resource representations)
   • Zelf-omschrijvende berichten
   • Hypermedia als de drijvende kracht van de applicatie status. De applicatie in deze context is de web applicatie die je server runt, hypermedia de hyperlinks/links die de server meestuurt in het antwoord.
      
5. Layered system: Een gelaagd systeem staat de API toe om opgebouwd te worden in hierarchische lagen, door te zorgen dat ieder component niet voorbij de directe laag waar het in opereert kan 'kijken'. In deze context gaat het om een laag van servers.
    
6. Code on demand (optioneel): REST staat clients toe om code te downloaden en uitvoeren in de vorm van applets of scripts. Dit vereenvoudigt clients door het aantal features dat geïmplementeerd moet worden terug te brengen.

API-requests en responses

Een API communiceert via requests en responses. In het API-voorbeeld van een restaurant is je bestelling een request, waarbij het bezorgde eten een response is. Er zijn verschillende requests die afhankelijk van de implementatie door een API kunnen worden uitgevoerd. In de TransIP REST API worden de volgende requests gebruikt:

• GET: Verzoekt om een 'resource' van een server, waarbij een resource een speciale variabele is (de resource representation) die een referentie tot een externe resource bevat. De data kan vervolgens worden aangepast en teruggestuurt met een PUT-request.
• POST: Een client voegt een nieuwe resource toe, bijvoorbeeld de bestelling van een product.
• PUT: Update een resource met nieuwe data, bestaande data wordt verwijderd. Dit gebruik je bijvoorbeeld als je met een GET request de specificaties van een VPS opvraagt, de description aanpast en het gehele array terug plaatst.
• PATCH: Wordt niet standaard gebruikt in API's, maar is wel aanwezig in onze REST API. PATCH wordt gebruikt voor een gedeeltelijke update van een resource, bijvoorbeeld het stoppen/starten van een VPS.
• DELETE: Gebruik je voor het verwijderen van resources.

De API gebruikt JSON objecten en arrays voor alle requests en responses die via de API uitgevoerd worden.

Responses

Voor de responses wordt een HTTP status code gebruikt. Bij een succesvol request wordt er een 2xx HTTP status code teruggegeven:

Bij een foutmelding wordt een van de volgende status codes teruggegeven.

Daarmee zijn we aan het eind gekomen van dit artikel. Mocht je aan de hand van deze handleiding nog vragen hebben, aarzel dan niet om onze supportafdeling te benaderen. Je kunt hen bereiken via de knop 'Neem contact op' onderaan deze pagina.