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:


HTTP GET: Anvendes til at hente information.
HTTP POST: Anvendes til at oprette nye ressourcer.
HTTP PUT: Anvendes til at udskifte hele en eksisterende ressource.
HTTP PATCH: Anvendes til at opdatere enkelte dele af en eksisterende ressource.
HTTP DELETE: Anvendes til at slette ressourcer.


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.

  • No labels