Tilbakemeldinger til CERES på nytt REST API (v1)

CERES har lagt ut førsteutkast av ny REST API for FS, og INT har sett på dette, og har kommet med tilbakemeldinger.

Språk og terminologi

API inneholder mye terminologi og forkortelser som kan være uklare eller vanskelige å forstå uten detaljkunnskap om FS. Dette gjør også at intern logikk skinner gjennom i API-et.

F.eks.:

  • "studentKompentanse": "VE1". Hva er VE1 for oss som ikke har mellomfag i FS? Burde studentKompetanse være referanse til mer informasjon?

Språk

Attributtnavn og ressursnavn er delt mellom norsk (adresse, harBilde) og engelsk (size, items). Dette burde kanskje holdes til ett språk.

Her vil jeg gjerne foreslå min personlige preferanse: engelsk.

true/false

Returverdier bør ha fornuftig type. Hvorfor brukes "J"/"N" når JSON har innebygde datatyper for dette?

Eksempel: "harBilde": "N" → "harBilde": false

null-verdier

Verdier som er tomme, bør settes til null.

F.eks. manglende adresse:

...
"adresse": {
    "type": "HJEM",
    "postnr": 0
},
...

Her burde vel det vært:

...
"adresse": null,
...

Stedkoder

En person jeg slo opp på, hadde:

"fagpersonSted": {
  "meta": {
    "href": "https://docker-demo.fsat.no/fsapi/steder/0.0.0.0"
  },
  "institusjon": 0,
  "fakultet": 0,
  "institutt": 0,
  "gruppe": 0
}
  1. Verdi burde vært null - her er det ingen stedkode!
  2. Ser ut som URL til stedkode er /steder/<org>.<fac>.<inst>.<gr>, hva med /steder/<org>/<fac>/<inst>/<gr>. Da kunne denne ressursen også bli benyttet som organisasjonskart, og f.eks. /steder/<org> kunne gitt informasjon om institusjon, og liste over fakulteter.

Adresser

Valg av adresse, adressetyper

Hvilken adresse vil man få? Er dette avhengig av hvilke roller personen har? Det ser ut som det bare er type HJEM som kommer ut her? Antar det er en feil (mangel) at ikke andre typer vises?

I Cerebrum importerer vi flere adresser for personer, avhengig av rolle:

  • Fagperson: fs.fagperson._arbeide, fs.person._hjemsted
  • Student: fs.person._hjemsted, fs.student._semadr
  • EVU: fs.deltaker._job, fs.deltaker._hjem

Vi vil gjerne at API-et gir oss akkurat de adressene som vi er interesserte i, og jeg ser egentlig for meg at vi bare har behov for en adresse, men da må det være den riktige adressen...

Jeg innbiller meg at andre tjenester vil ha behov for å plukke ut spesifike adresser, f.eks. /personer/n/adresse/arbeid. Slik som adresse gies nå, vil vi kanskje ha redusert mulighet for å bytte ut eller utvide dette senere?

Jeg ser for meg at kanskje adresse burde leve under /personer/n/adresse/<type>, og at /personer/n/adresse inneholder referanse til alle eksisterende adresser for en person, samt en indikator/referanse til den adressen som nå dukker opp i adresse-atributtet i /personer/n.

Adresse-modell

"adresse": {
  ...
  "sted": "1363 HØVIK",
  "postnr": 1363
}

Skal sted inneholde postnummer? Hvordan ser evt. internasjonale adresser ut? Eller postboks? Eller finnes ikke dette i FS?

Hvilke verdier finnes for "type"?

Det ser slik ut ved utenlandsk adresse:

"adresse": {
    "type": "HJEM",
    "co": "c/o John Doe",
    "gate": "38, Casale San Nicola",
    "sted": "83038 - Montemiletto (AV)",
    "postnr": 0,
    "land": "Italy"
  },

Internasjonale adresser burde heller hatt et annet format (felter).

Telefon

Slik som det ser ut, får vi bare et telefon-felt. For bruk i integrasjon med Cerebrum, så er dette glimrende! Vi er egentlig kun interessert i mobilnummer. Men hva om en annen tjeneste kommer på plass, og kun er interessert i f.eks. faksnummer eller telefonnummer?

Antar det er ein feil (mangel) at ikke andre typer enn MOBIL vises?

Hvilke verdier finnes for "type" (er dette opplistet noe sted)? Og hva benyttes feltet til? Hvilken verdi får vi hvis det finnes flere telefonnummer i FS? Hva om eneste telefonnummer er FAKS?

/personer

query-parameter

RFC2396 sier lite om hvordan boolske query-parameter skal utformes, men hadde det vært en ide å gå for noe som er litt vanligere enn J/N? F.eks.:

  • api/resource?hasProperty=true&otherProperty=false
  • api/resource?hasProperty=1&otherProperty=0
  • api/resource?hasProperty=yes&otherProperty=no

Eventuelt noe litt mindre verbost: /persons/?select=student,studrett

Utplukk

Hva skjer om jeg slår opp på fagperson=J&student=J?

  • Får jeg union av alle personer som er enten fagperson eller student?
    • Hvordan vet jeg i så fall om personen er fagperson og/eller student i resultatet?
  • Får jeg snitt altså personer som er både fagperson og student?
    • Hva om jeg ber om fagperson=N&fagpersonAktiv=J?

Hva skjer om jeg ber om GET /personer? Hvilke personer er med i utplukket hvis jeg ikke oppgir verdi for personroller eller semreg?

Dokumentasjon

I følge swagger-docs så returnerer GET /personer en liste med fulle personobjekter (liste med objekter, hvor hvert objekt har samme schema som /personer/n).

Jeg er usikker på hva som er riktig her, for alle søk som jeg har forsøkt resulterer i liste med referanser:

{
  "meta": {
    "href": "https://docker-demo.fsat.no/fsapi/personer",
    "rel": [ "collection" ]
  },
  "size": 6378,
  "items": [
    {
      "meta": {
        "href": "https://docker-demo.fsat.no/fsapi/personer/n"
      },
      "lopenr": n
    },
    ...
  ]
}

Tipper det er doken som er feil.

Filtrering/søkemuligheter

Det kunne vært nytting for oss med flere filtreringsmuligheter i «personsøket». Dette for å kunne gjøre feilsøking, feilretting og testing.

Mulighet for å filtrere etter person-ider som studentnummer/ansattnummer vil gjøre det mulig å slå opp på "kjent informasjon", for å sammenligne entiteter i flere systemer. Det vil også gjøre det mulig for oss å f.eks. gjøre synk av enkeltpersoner, dersom det skulle oppstå feil.

Mulighet for å filtrere etter stedkode kunne hjulpet ved å gi oss mindre datasett for testing, samt muliggjort en gradvis utrulling av ny FS-synk.

Timeouts

Jeg slet med testing av /personer - spørringer tar en del tid, og de fleste spørringer resulterer i en 504 Gateway Timeout. Antar at dette kommer seg i senere versjoner.

camelCase

Dette er i høyeste grad personlig preferanse, men jeg vil gjerne slå et slag for å bruke lowercase/snake_case fremfor camelCase (studentKompetanse, fagpersonSted) i attributtnavn.

Grunnen til å ta det opp er å unngå at verdier kan bli overskrevet i parsing av JSON-output:

$ echo '{"foo": "bar", "Foo": "baz"}' | jq
{
  "foo": "bar",
  "Foo": "baz"
}
$ echo '{"foo": "bar", "Foo": "baz"}' | tr '[:upper:]' '[:lower:]' | jq
{
  "foo": "baz"
}

Dette gjør at samme navnestandard kan brukes som ressursnavn/url og attributt-navn:

$ GET /collection/<id>

< {
<   "id": "<id>",
<   ...
<   "some_resource": {
<     "href": /collection/<id>/some_resource
<   }
< }

> GET /collection/<id>/some_resource

< {
<   "foo": true,
<   ...
< }
Publisert 27. mars 2017 19:46 - Sist endret 27. mars 2017 19:49
Del på e-post