REST api design guidelines

Voor een intern project ben ik bezig om een RESTful api op te zetten met behulp van ASP.NET MVC.
Daarbij wil ik dat je content zowel in HTML5 als JSON op kunt vragen.

Hiervoor wilde ik guidelines opstellen zodat ik een consistente api krijg en je de urls naar de resources kunt raden.

Hierbij ben ik op de volgende guidelines uitgekomen:

1. Gebruik zelfstandige naamwoorden
In een REST interface draait alles om resources, dit zijn daardoor per definitie 'dingen'
Daarnaast maak ik gebruik van de meervouden om collecties uit te drukken.

Een voorbeeld om alle bedrijven op te vragen:


/companies (geeft een lijst van alle bedrijven)
/companies/Oosterkamp (geeft alleen het bedrijf Oosterkamp terug)

Het weergeven van 'master/detail' onderwerpen, heb ik als volgt opgelost:
/companies/Oosterkamp/employees (geef alle medewerkers van Oosterkamp)
/projects/2011001/hours (geef alle uren geboekt op project 2011001)
/projects/2011001/invoices (geef alle facturen voor project 2011001)


2. Gebruik geen werkwoorden
Gebruik geen werkwoorden, het is geen RPC of SOAP-service!

De enige operaties die mogelijk zijn worden uitgedrukt met HTTP verbs,
POST voor inserts (Create),
GET om resources op te halen (Read),
PUT voor wijzigingen (Update),
DELETE om resources weg te gooien (Delete)

Zoals je ziet levert dit een mooie CRUD interface op.

3. 'Moeilijke zaken' oplossen met querystring
Overige zaken die lastig op te lossen zijn (omdat het een werkwoord is bijv.) in de querystring stoppen.
Een voorbeeld hiervan is het zoeken van een bedrijf:


/companies?search=A* (zoekt bedrijven die met een A beginnen)
/companies?limit=100&offset=0 (paging, 100 resultaten, 1e pagina)


4. Gebruik standaard HTTP status codes voor fouten
Wanneer je een foutmelding geeft, gebruik dan een standaard status code.
200 - OK, 't is gelukt
404 - Resource not found, kan het 'ding'  niet vinden
401 - Unauthorized,  je hebt geen toegang tot het 'ding'


5. Content in meerdere formaten opvragen
De urls geven resources aan die in het systeem zitten. Wanneer ik deze resource in een specifiek formaat wil opvragen moet ik een manier hebben om dit op te vragen.

Wat mij betreft zijn daar twee oplossingen voor:
Met een extensie:
/companies.html
/companies/Oosterkamp.json
/companies/Oosterkamp/employees.xml

Met een querystring:
/companies?format=html
/companies/Oosterkamp?format=json
/companies/Oosterkamp/employees?format=xml

Op onder andere http://blog.apigee.com/detail/restfulapidesign/ heb ik mijn idee├źn gevalideerd en zijn nog meer handige tips te vinden.

Ronald Harmsen

I'm a software developer. When I'm not developing software I'm training & coaching other developers, speaking on a conference or fiddling with some technical stuff.

Arnhem, The Netherlands

Subscribe to Ronald to the cloud

Get the latest posts delivered right to your inbox.

or subscribe via RSS with Feedly!