Tasks API introduktion

Introduktion

Tasks API’et er implementeret som “vanilla” XML over HTTP. Med “vanilla” menes at XML’en er helt basal, uden komplicerede strukturer eller typer, skemaer eller lignende. Dermed har vi gjort det så enkelt som overhovedet muligt at bruge API’et.

Kald til API’et foregår via HTTP og følger principperne for REST. Det vil sige at hvert kald skal specificere en HTTP verb der indikerer hvilken type handling man ønsker at foretage. Vi bruger 4 typer:

POST – bruges når man vil oprette data.
PUT – bruges når man vil opdatere data.
GET – bruges når man vil hente data.
DELETE – bruges når man vil slette data.

Hvordan man gør i praksis vil man kunne se af kodeeksempler på de øvrige sider.

Autentificering

Man giver sig til kende ved at medsende en API key i HTTP headeren “Authorization”. Du kan på forsiden se hvordan du får fat i denne key. Du skal medsende denne key hver gang du laver et kald.

Her er et eksempel på autentificering i C#:

WebRequest request = WebRequest.Create("https://app.tasks.dk/api/clients");
request.Headers.Add("Authorization", "din-api-key");

Og i PHP:

$session = curl_init();
curl_setopt($session, CURLOPT_HTTPHEADER, array('Authorization: din-api-key'));
curl_setopt($session, CURLOPT_URL, 'https://app.tasks.dk/api/clients');

Hvis du af en eller anden grund ikke ønsker at opbevare API-keyen i din applikation, kan du bruge Hent konto til at logge på og hente keyen.

Bemærk at alle GET kald (alle der hedder noget med hent) kan foretages direkte i en browser, når du er logget ind i Tasks. Derved kan du hurtigt se hvad en given funktion returnerer.

Svar og statuskoder

For hvert kald bliver der sendt et svar, uanset hvad. I svaret angives en statuskode, som så vidt muligt følger de officielle HTTP statuskoder. Generelt vil der altid blive returneret 200, hvis kaldet gik godt. Statuskoder i 4xx-rangen (minus 409) er oftest selvforskyldt, for at sige det lidt groft. Statuskoderne ses i tabellen herunder:

Kode	Besked	Forklaring
200		Alt OK!
401	Authorization token not provided	Ingen API key medsendt i HTTP headeren “Authentication”.
403	Authorization unsuccessful	Der kunne ikke autentificeres med den medsendte API key.
403	Account subscription has expired	API key godkendt, men abonnement udløbet.
403	Id not provided or id is not an integer	Der er ikke angivet et id i URL’en eller id’et er ikke numerisk.
404	Provided [type] id does not exist	Der er forsøgt at operere på et id der enten ikke findes eller ikke tilhører kontoen.
405	Only [verb] [is\|are] allowed here	Der er forsøgt at bruge en verb der ikke kan bruges for pågældende URL.
406	One or more fields are missing, malformed or do not obey the rules. Please refer to the documentation.	Et eller flere påkrævede felter er ikke angivet eller udfyldt forkert eller overholder ikke de beskrevne regler.
409	[type] cannot be deleted due to dependencies	Der er forsøgt at slette et objekt der ikke kan slettes pga. afhængigheder til andre data. Eksempelvis hvis en timeregistrering indgår i en bogført faktura.
500	Unhandled exception occured. It has been logged and will be taken care of ASAP.	Der opstod en uforudset fejl. Fejlen er logget og der vil blive taget hånd om den så hurtigt som muligt.

XML-strukturen for et svar ser således ud:

<reply>
   <status>
      <code>xxx</code>
      <name>HTTP status code definition name</name>
      <message>Evt. forklarende besked</message>
   </status>
   <data>
   ...
   </data>
</reply>

‘name’ indeholder det officielle navn for statuskoden (fx Forbidden, Not Found), mens ‘message’ vil indeholde en mere detaljeret beskrivelse af hvad der er galt. De mulige beskeder ses i Besked-kolonnen i ovenstående tabel.

‘data’-elementet vil afhænge af hvilken type data og handling man arbejder med.

Båndbreddemæssige begrænsninger

Der er endnu intet max på antal kald man kan foretage, men alle kald logges for at forhindre overdreven brug. Skulle det blive nødvendigt, forbeholder vi os retten til at indføre en grænse for antal kald per time eller døgn. Dette vil blive varslet i god tid.

Funktionsmæssige begrænsninger

Det primære formål med API’et er dataudveksling. Derfor er visse funktioner fra brugergrænsefladen ikke implementeret i API’et. Følgende funktioner er ikke implementeret eller eksponeret:

Samtlige mail-funktioner (notifikationer m.v.)
Vedhæftede filer til kommentarer.
Alt vedrørende klippekort.
Opret, rediger og slet bruger.
Alt vedrørende e-conomic integration.

Det er tanken at der også skal være eksponering af fakturaer i et vist omfang. Det afhænger dog af efterspørgslen.