Hente og redigere data

Hente og redigere data

Alle API-forespørsler sendes til brukerens Dokus-adresse, som er https://subdomene.dokus.no, hvor subdomene erstattes med organisasjonens selvvalgte subdomene.

Alle forespørsler sendes og mottas som JSON, og API-klienter må sette HTTP-headeren Accept til application/json. Ved opprettelse og endring av data, må også HTTP-headeren Content-Type settes til application/json.

Hente ressurser

Ressurser hentes enkeltvis eller i lister ved å foreta en HTTP GET til ressursens URL.

Eksempel med cURL:

curl -u [email protected]:passord -H 'Accept: application/json' https://mittfirma.dokus.no/products/

Ressursen returneres som JSON:

{
    "product": {
        "id": 3,
        "name": "The Definitive Guide to Django", 
        "comment": "Paperback, 2009", 
        "price": "199.50", 
        "creation_time": "2010-04-26 11:18:35", 
        "modification_time": "2010-10-08 11:56:28", 
        "creation_by": {
            "id": 1,
            "first_name": "Ole Nordmann", 
            "email": "[email protected]"
        }, 
        "product_number": "1234", 
        "modification_by": {
            "id": 1,
            "first_name": "Ole Nordmann", 
            "email": "[email protected]"
        }, 
        "default_vat_class": {
            "id": 1,
            "name": "High VAT"
        }
    }
}

Ressurser hentes på to måter; enkeltvis eller som en liste.

Et enkelt produkt hentes ved å gå til ressursens URL, etterfulgt av produktets ID, f.eks. /products/412/.

Ressursenes hentes som en liste ved å gå til ressursens URL, for eksempel /products/. Noen av liste-metodene støtter filtrering, slik at man kan begrense listen til ressurser som oppfyller søkekriterier. Eksempelvis kan alle fakturaer sendt til en mottaker med et navn som inneholder "test" hentes på URL-en /invoices/?recipient_name=test. Tilgjengelige søkekriterier er dokumentert på detaljsidene til hver ressurs.

Opprette og endre ressurser

Ressurser opprettes eller endres ved å sende dataene som JSON til ressursens URL som HTTP POST.

curl -u [email protected]:passord -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{"name":"The Definitive Guide to Django","comment":"Paperback, 2009","price":"199.50","product_number":"1234","default_vat_class":"1"}' https://dokus.no/products/create/

Merk at når data sendes som JSON, må HTTP-headeren Content-Type settes til application/json.

{
    "name": "The Definitive Guide to Django", 
    "comment": "Paperback, 2009", 
    "price": "199.50", 
    "product_number": "1234", 
    "default_vat_class": 1
}

For å opprette ressurs sendes forespørselen typisk til en URL som slutter på /create/ (f.eks. https://mittfirma.dokus.no/products/create/, mens oppdateringer postes direkte til ressursens URL (f.eks. https://mittfirma.dokus.no/products/3/).

Om ressursen ble opprettet/oppdatert, returneres HTTP-status 200, sammen med den oppdaterte ressursen som JSON.

Dersom ressursen ikke ble oppdatert pga. ugyldige verdier returneres HTTP-status 401 (Bad Request), og feilmeldingen sendes tilbake i JSON.

Det er kun nødvendig å sende med ressursens redigerbare felter. Felter som kun er lesbare (f.eks. modification_time som settes automatisk) blir ignorert av API-et.

Relasjonsfelter

Felter som angir relasjoner til andre ressurser, som default_vat_class i eksempelet over, kan angis i fullstendig form eller kun ved å bruke ressursens ID. Når feltet angis i fullstendig form henter systemet ut ID-feltet, og ser bort fra de øvrige feltene.

Feltet default_vat_class angitt i fullstendig form:

{
    "name": "The Definitive Guide to Django", 
    "default_vat_class": {
        "id": 1,
        "name": "High VAT"
     }
}

Feltet default_vat_class angitt kun som ID:

{
    "name": "The Definitive Guide to Django", 
    "default_vat_class": 1
}

Slette ressurser

For å slette en ressurs sendes en HTTP POST til ressursens URL, etterfulgt av /delete/ (f.eks. https://mittfirma.dokus.no/products/3/delete/).

Ressursen slettes, og Dokus API returnerer HTTP-statuskode 204.