Denne side beskriver reglerne, som gælder for REST services udstillet af komponenterne på NSP.
1 § REST services skal kunne modtage og svare med beskeder, der er formateret som JSON. Svaret skal indeholde http header: "Content-Type: application/json". |
2 § En REST service skal anvende HTTP verberne som følger:
|
3 § REST services skal anvende navneord frem for verber i URL’en til at beskrive servicen. |
For at hente en aftale gennem en REST service eksempelvist: ”/aftale” er korrekt, mens ”/hentaftale” er forkert.
4 § Såfremt en REST service returnerer collections, anvendes flertalsformen i URL’en. |
Eksempelvis ”/aftaler”.
5 § Såfremt REST servicen giver mulighed for at hente enkelte attributter, bør de kunne specificeres i URL’en. |
Dette kan være "/aftaler/<aftale-id>/starttime", hvor "starttime" er en enkel attribut.
6 § Såfremt en REST service tilbyder filtrering, sortering eller paginering af svaret, skal det ske via søgeparametre i URL’en. |
Eksempelvis et HTTP GET kald mod "/articles/?page=1&page_size=10".
7 § Såfremt der er behov for at versionere en REST service, skal versionsnummeret være det første element i URL’ens path del. |
Eksempelvis "2020/02/24/aftaler", hvor snitfladen er versioneret som Namespaces, se 2.9.5 § i Husregler for udvikling til NSP#Webservices.
Her kan der benyttes et servlet filter til at få fat i versionen, og placere den på en servlet context. Den kan således anvendes til at skelne mellem forskellig logik på tværs af versioner.
8 § REST services skal returnere HTTP statuskoder ved succesfuld transaktion: GET: 200 OK. POST: 201 Created. PUT: 200 OK. PATCH: 200 OK. DELETE: 204 No Content. |
9 § Ved fejl transaktion returneres passende HTTP statuskode. |
Standard HTTP statuskoderne benyttes til dette formål. Ved klient fejl returneres en HTTP 4xx fejlkode, og ved server fejl en HTTP 5xx fejlkode.
10 § En REST service skal kommunikere eventuelle begrænsninger i svaret. |
Dette kan være begrænsninger i antal elementer der kan returneres, f.eks. ved loft på 10 aftaler fra en REST service "/aftaler", returneres HTTP "413 Content Too Large".
11 § En REST service skal designes så den er stateless. |
12 § En REST service bør understøtte HTTP caching, når det er relevant. |
F.eks. ved hjælp af ETag HTTP response header / Last-modified eller andre age-controlling headers.