Webtjenester, eller webservices på engelsk, også kalt SOA, er tjenester vi tilbyr for kommunikasjon mot våre applikasjoner og databaser. Disse tjenestene er her presentert som CWS (Connect Web Services). CWS API'et benytter et REST-lignende grensesnitt. (se http://en.wikipedia.org/wiki/REST). Dette betyr at våre CWS metodekall blir gjort over internett ved å sende HTTP GET eller POST forespørsler til CWS REST-serveren. Nær sagt ethvert programmeringsspråk kan benyttes for å kommunisere over HTTP med REST-serveren.
Det første som må implementeres av klienten er selve innloggingsprosedyren til CWS. Du må få tildelt brukernavn og passord før du logge inn. CWS benytter Basic Autentication. Dette betyr at brukernavn og passord sendes med hver forespørsel i HTTPs Authorization-header. De fleste HTTP-biblioteker har innebygd støtte for slik autentisering.
Alle forespørsler som ikke inneholder gyldig autentiseringsinformasjon blir avvist med responskode 401 (Unauthorized)
Alle tjenestekall i dokumentet baserer seg på en tjeneste applikasjons-kontekst. Applikasjons-konteksten bestemmes ut fra hvor/hvordan CWS installeres. Et eksempel på en slik applikasjons-kontekst er: https://cws.mediaconnect.no/cws
Alle kall returnerer en header som identifiserer versjonen av CWS (og Connect) som benyttes. Headeren heter X-Connect-Version. Denne kan brukes dersom man skal rapportere inn feil, eller for å identifisere hvilke tjenester som er tilgjengelig.
All xml som CWS returnerer vil være UTF-8 kodet:
<?xml version="1.0" encoding="UTF-8"?>.
All xml som sendes inn til CWS vil bli tolket i UTF-8.
Hvis du manuelt bygger opp HTTP POST forespørslene til CWS, må du inkludere forespørseldataene i POST-body'en. I tillegg skal du inkludere følgende Content-Type: application/x-www-form-urlencoded.
Hver bruker kan ha 1 til mange klienter tilknyttet. Du må få tildelt en eller flere klient-id'er før du kan benytte CWS. Klient brukes for autorisasjon av hvilke tjenester, operasjoner og data som er tilgjengelig fra systemet. Hvilken klient som skal brukes identifiseres vha. en klient-id ("client id"). Klient-id må tas med som en del av ressurs-uri'en for å identifisere hvilken klient som skal brukes ved gjeldende metodekall.
Eksempel på URI for henting av kundedata for spesifikk kunde (med kundenummer=10), klient-id er "1":
/client/1/customer/10
Det finnes ingen DTD som kan brukes for å validere et XML-dokument som du mottar av CWS. Grunnent til dette er at vi har designet våre systemer på en slik måte at endringer i XML-dokumentene ikke krever endringer av CWS sine klienter, dvs ditt dataprogram. Dette er til stor hjelp både for deg og oss.
CWS returnerer følgende responskoder på en HTTP-kommando:
Alle tjenestene returnerer feil hvis uforutsette ting skjer. Dette kan f.eks. være ugyldig formatert XML. I slike tilfeller er ALLTID responskoden 500 - Intern feil.
Ved slike feil kan det enten returneres en formattert XML som vist nedenfor, eller en generell feilmelding i klartekst hvis systemet ikke har klart å tolke feilen internt i systemet før den returneres.
Eksempel på generelle feil som kan returneres fra alle tjenestene:
<?xml version="1.0" encoding="UTF-8"?> <error> <errorMessage>Element 'productSpecType' contains invalid value</errorMessage> <messages> <message>Element 'productSpecType' contains invalid value: 'Coupon'</message> </messages> </error>
Beskrivelse av de forskjellige XML-elementene i en generell feilmelding fra CWS:
Elementnavn | Elementets forelder (parent) | Elementbeskrivelse | Datatype |
---|---|---|---|
<error> | - | Rot-element Dette er rot-elementet som inneholder feilmeldingen | - |
<errorMessage> | <error> | Feilmelding Inneholder en tekstuell beskrivelse av feilmeldingen | Tekst |
<messages> | <error> | Inneholder en liste av detaljerte feilmeldinger | - |
<message> | <messages> | Detaljert melding En detaljert feilmelding | Tekst |
For enkle tester av tjenestene kan du bruke en browser (Firefox, Chrome, etc), wget eller curl.
GET forespørsler kan enkelt testes ved å bruke en browser. Internett-adressen er adressen til tjenesten: http://cws.mediaconnect.no/cws/client
Eksempel på curl kommandolinje for tjeneste som forventer en GET forespørsel:
curl --insecure -u username:password https://cws.mediaconnect.no/cws/client
Tjenester som forventer POST forespørsler er typiske tjenester som trenger XML data i POST-body'en. curl kan enkelt brukes for å oversende disse dataene fra en fil:
curl --insecure --data @order.xml -u username:password https://cws.mediaconnect.no/cws/client/10/order
I tilfeller der man skal sende inn XML, kan det være greit å teste at XML'en man lager er OK før man sender den inn til tjenesten. Til dette kan man bruke netcat (eller nc).