API:et är designat på REST – Representational State Transfer – som är en teknik som vuxit sig stark under senare år.

Till skillnad från SOAP, som är en annan standard för kommunikation över HTTP, så är REST mycket mer lättvikt, enklare att implementera och använda även för simpla klienter. Detta eftersom kommunikationen utgörs av standard HTTP-anrop. SOAP-anrop är låsta till XML, medan REST har stöd för godtyckliga format som ex lättviktsformatet JSON.

En kugge i designprinciperna för REST är att man exponerar data istället för metoder. Varje resurs i datan är unikt adresserbar med en URL, som följer en mönster så utvecklare kan känna igen sig i strukturen utan några direkta förkunskaper om API:et. Andra styrkor är att REST är prestandamässigt starkt, bra att skala upp och har läs-anrop som kan cachas.



Kommunikationen mellan klienter och API:et är REST-baserad, vilket innebär att data skickas över HTTP.
HTTP-kommunikationen bygger på att klienten skickar ett anrop till servern som processar och skickar ett svar tillbaka.

Ett anrop består av
ett HTTP-verb
en resurs-URL
ev querystring-parametrar
HTTP-headers
ev request-data

Svaret består av
en statuskod
HTTP-headers
ev response-data

Exempel på anrop:

AnropSvar
PUT http://server/api/fi2entity/123
Host: server 
Accept: application/xml

<fi2entity id="123"> <fi2entity_value> <fi2value_code>CreatedDate</fi2value_code> <fi2value_scheme> <fi2scheme_id>VB001_005_001</fi2scheme_id> <fi2scheme_name>Värden</fi2scheme_name> <fi2scheme_url>VB001_005_001</fi2scheme_url> </fi2value_scheme> <fi2value_value>2014-03-26</fi2value_value> </fi2entity_value> </fi2entity>
200 OK
Content-Type: application/xml; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Aug 2012 13:50:37 GMT
Content-Length: 696

<fi2entity id="123"> <fi2entity_value> <fi2value_code>CreatedDate</fi2value_code> <fi2value_scheme> <fi2scheme_id>VB001_005_001</fi2scheme_id> <fi2scheme_name>Värden</fi2scheme_name> <fi2scheme_url>VB001_005_001</fi2scheme_url> </fi2value_scheme> <fi2value_value>2014-03-26</fi2value_value> </fi2entity_value> </fi2entity>

Anges en mediatyp, teckenkodning eller culture i HTTP request headern som inte stöds av API:et ignoreras detta och default värden används.

Mediatyper som stöds av API:et
  • application/xml (default)
Teckenkodning som stöds av API:et
  • UTF-8 (default)
Cultures som stöds av API:et
  • sv-SE (default)




De anrop som API:et kan stödja anges här:

AnropHTTP-VerbResurs-URLExempel
Hämta alla objektGET/api/<entitet>GET /api/fi2leasecontract
Hämta ett specifikt objektGET/api/<entitet>/<id>GET /api/fi2leasecontract/123
Skapa ett nytt objektPOST/api/<entitet>POST /api/fi2leasecontract <xml-data>
Uppdatera ett objektPUT/api/<entitet>/<id>PUT /api/fi2leasecontract/123 <xml-data>
Ta bort ett objektDELETE/api/<entitet>/<id>DELETE /api/fi2leasecontract/123

De REST-entiteter som API:et stöder anrop emot finns listade under sektionen API Datamodell.
För respektive entitet finns de anrop som stöds av API:et listat under rubriken Operationer.




De HTTP-statuskoder som API:et använder anges här:

HTTP-VerbStatuskodBeskrivning
(Alla) 400 Bad Request Ett fel har uppstått p.g.a. felaktigt indata
403 Forbidden Ej behörighet att utföra anropet
500 Internal Server Error Ett oväntat fel har uppstått
501 Not Implemented Funktionen är inte implementerad i systemet
GET 200 OK Det gick bra att hämta resurs
404 NotFound Den efterfrågade resursen finns inte
PUT 200 OK Det gick bra att uppdatera resursen
404 Not Found Den efterfrågade resursen finns inte
POST 201 Created Resursen har skapats
DELETE 204 No Content Det gick bra att ta bort resursen
404 Not Found Den efterfrågade resursen finns inte

För mer information om samtliga HTTP-statuskoder:
http://www.iana.org/assignments/http-status-codes/http-status-codes.xml