Introduksjon

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.

Innlogging

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)

Tjeneste applikasjons-kontekst

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

Connect versjon

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.

Felles standard info i alle webtjenester

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.

Klienter

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

XML

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.

HTTP-responskoder

CWS returnerer følgende responskoder på en HTTP-kommando:

  • 200 Ok
    HTTP-kommandoen ble utført. Serveren vil også returnere resultatet av prosesseringen.
  • 204 Ingen respons
    HTTP-kommandoen ble utført, men det er ingen returdata. Kan forekomme når du f.eks. kjører en spørring som ikke inneholder noe returdata.
  • 400 Ugyldig HTTP-kommando
    HTTP-parametrene er mangelfull. Man kan som regel enkelt finne ut hva som er problemet ved å lese feilmeldingen som følger responsen.
  • 401 Uautorisert
    Autentisering feilet.
  • 500 Intern feil
    Serveren feilet uventet og HTTP-kommandoen ble avbrutt (ikke gjennomført).

Feilmeldinger ved HTTP-responskode 500 - Intern feil

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:

ElementnavnElementets forelder 
(parent)
ElementbeskrivelseDatatype
<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

Test av tjenestene

For enkle tester av tjenestene kan du bruke en browser (Firefox, Chrome, etc), wget eller curl.

GET forespørsler

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

POST forespørsler

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

Testing av POST med netcat

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).

  • Start programmet med: netcat -l -p 8888 (Programmet lytter på port 8888.)
  • Test klienten ved å endre URL'en til maskinen som kjører netcat. (Husk riktig port.)
  • Konsollet vil fylles med innholdet av forespørselen. Avslutt med ctrl + c.