Dokumentation af Web API

Et af formålene med Køservicen web servicen er at eksperimentere med, hvorledes en REST web service med fordel kan designes. Af denne grund er der mulighed for at nedenstående Web API løbende ændres.

Baseadresse: https://www.oiorest.dk/queueservice/v1

Resource URI Method Repræsentation Status Beskrivelse Rolle med rettighed
Ejere /owners GET XML beskrevet i owners.xsd 200, 405, 500 Modtag liste over ejere/td> Alle
Ejer /owners/{ownersid}

 GET XML beskrevet i owner.xsd 200, 404, 405, 500 Modtag ejer Alle
  /my
 GET XML beskrevet i owner.xsd 200, 401, 404, 405, 500 Modtag ejer Ejer
  /my PUT Ingen 200, 403, 405,  500 Opret/Tilmeld ejer Alle
  /my DELETE Ingen 200, 401, 403, 405, 500 Slet/Frameld ejer Ejer
Køer /owners/{ownerid}/queues

/my/queues		 GET XML beskrevet i queues.xsd 200,
401, 405, 500		 Modtag en ejers køer Medlemmer
Kø /my/queues/{queueid} GET XML beskrevet i queue.xsd 200,
401, 404, 405, 500		 Modtag oplysninger om kø Ejer
    PUT Ingen 200, 401, 403, 405, 500 Opret kø Ejer
    DELETE Ingen 200, 401, 403, 405,  500 Slet kø. Skal være tømt for beskeder. Ejer
Køtyper /queuetypes GET XML beskrevet i queuetypes.xsd 200, 405, 500 Modtag en liste over køtyper Alle
Beskeder /my/queues/{queueid}/messages GET XML beskrevet i messages.xsd 200,
401, 403, 405, 500		 Modtag en liste over køens beskeder Ejer
Besked /owners/{ownerid}/queues/{queueid}/messages/{messageid}

/my/queues/{queueid}/messages/{messageid}
 GET XML beskrevet i message.xsd 200, 401, 403, 404, 405, 500 Modtag beskeden Ejer
    DELETE Ingen  200, 401,  403, 405, 500 Fjern beskeden fra køen. Forsæt indtil der er modtaget et svar. Ejer
DokumentId /owners/{ownerid}/queues/{queueid}/newdocumentid

/my/queues/{queueid}/newdocumentid		 GET XML beskrevet i documentid.xsd 200,
401, 405, 500		 Modtag et dokumentid, som anvendes til at tilføje et dokument i et medlems kø. Medlemmer
Dokument /my/queues/{queueid}/messages/{messageid}/document
 GET Dokumenttypen afhænger af mediatype angivet af  køtypen 200, 401, 403, 404, 405, 500 Modtag dokumentet Ejer
  /owners/{ownerid}/queues/{queueid}/messages/{messageid}/document PUT Dokumenttypen afhænger af mediatype angivet af  køtypen 200, 401, 400,  405, 500 Tilføj et dokument I køen. Forsæt indtil der er returneret et succesfuldt svar. Brug resourcen DokumentId til at modtage en gyldig URL til dokumentet. Medlemmer
Feed /my/feed GET Atom Syndication Format 200, 403, 405, 500 Modtag samlet liste over modtagne beskeder fra alle køer Ejer

Ownerid

Ownerid er en lettere modificeret udgave subject serial number fra ejerens OCES certifikat, som er maksimalt 64 tegn. Modifikationen består af at ":" er erstattet af "_" for at gøre ownerid URL-venlig.

my

/my er en kort skrivemåde for /owners/{ownerid}, hvor {ownerid} er ownerid for den aktuelle autentificerede bruger.

Roller

Køservicen anvender tre roller: alle, medlemmer og ejere. Alle er ejere af et OCES certifikat. Medlemmer er ejere af et OCES certifikat, som har tilmeldt sig Køservicen. Tilmeldingen fore går ved at foretage et "PUT" på /owners/{ownerid} eller på /my. Herefter har ejeren mulighed for at oprette køer, som andre medlemmer kan sende dokumenter til. En ejer er et medlem af køservicen, som har oprettet sine private køer, som andre medlemmer kan sende til, men som kun ejeren kan læse (GET) og slette (DELETE) fra.

Statuskoder

Alle statuskoder er inkluderet i HTTP Status header.De anvendte statuskoder er :

  • 200: Success (upon a successful GET, PUT, or DELETE request)
  • 400: Resource Invalid (improperly formatted request)
  • 401: Unauthorized (incorrect or missing authentication credentials)
  • 403: Forbidden
  • 404: Resource Not Found
  • 405: Method Not Allowed
  • 406: Not Acceptable
  • 500: Application Error

På vegne af

Trustede consumers har mulighed for at tilgå køservicen på vegne af andre. En trusted consumer er typisk et web site, som på vegne af en af deres authentificerede brugere, tilgår brugerens data. Der skal etableres et trust-forhold/aftale mellem køservicen og web sitet før web sitet kan opfattes som en trusted consumer.

Den trustede consumer autentificerer sig over for køservicen vha. et OCES certifikat, som alle andre serviceaftagere. Hvilken bruger, den trustede consumer handler på vegne af, angives vha. en http header i følgende format:

X-On-Behalf-Of: {SSN},{CN}

SSN og CN er henholdsvis Subject Serial Number og Common Name fra brugerens OCES certifikat.

Http headere anvender US-ASCII tegnsættet. {SSN},{CN} skal derfor URL encodes i UTF-8 (som beskrevet i RFC 2616) for at tegnene æ, ø, å, Æ, Ø og  Å  samt reserverede tegn uden problemer kan kommunikeres.

Testcertifikater

Til autentifikation overfor køservicen anvendes OCES certifikater. Hvis du ikke vil anvende dit eget, kan du anvende testcertifikater fra certifikat.dk. Hovedparten af testcertifikaterne er oprettet som medlemmer af køservicen. Det ikke spærrede virksomhedscerifikat med Common Name: "TDC TOTALLØSNINGER A/S - TDC Test" er registreret som trusted consumer.