API response format
bensinober opened this issue · 9 comments
The response format for /api/works and /api/reviews need to be consistent and reworked:
Response should be the same for GET/POST/PUT ?
proposal:
/api/works
returns json hash with Array
"works" => [
<uri1> => { "title" => (title),
"originalTitle" => (originalTitle),
"authors" => [
<uri1> => { "name" => (name1) },
<uri2> => { "name" => (name2) }
],
"isbns" => [ (isbn1), (isbn2), (isbn3) ]
"cover_url" => (cover_url),
"books" => [
<uri1> => { ?? },
<uri2> => { ?? }
],
"reviews" [
]
},
<uri2> => {...}
]
/api/reviews
returns json hash with Array
"reviews" => [
<uri1> => { "title" => (title),
"teaser" => (teaser),
"text" => (text),
"reviewer" => {
<uri> => { "name" => (name1) },
"workplace" => <uri> => { "name" => (name1) },
},
},
"source" => {
<uri> => { "name" => (name1) },
},
"audience" => {
<uri> => { "name" => (name1) },
},
"subject" => (isbn),
"cover_url" => (cover_url),
"work" => <uri>,
"book" => <uri>,
"created" => (date),
"issued" => (data),
"modified" => (date),
"published" => (bool),
},
<uri1> => {...}
]
ang. api/reviews:
Hvis det skal være mulig å clustre på verk, må ikke reviews være underlagt workuri på en eller annen måte?
Eks:
"works": {
"<work uri 1>": [{reviewdata... }, { reviewdata...}],
"<work uri 2>": [{reviewdata...}],
}Response should be the same for GET/POST/PUT ?
Yes please:)
Kommentarer til api/works:
Du tenker å ta med uri her?
"authors" => [
=> { "name" => (name1), "uri" => (uri)},
=> { "name" => (name2), "uri" => (uri) }
]"books" vil si manifestasjoner?
"books" => [ "<manifestasjonuri1>" , "<manifestasjonuri2>"],ang. api/reviews:
Hvis det skal være mulig å clustre på verk, må ikke reviews være underlagt workuri på en eller annen måte?
Mener du at både /api/reviews og /api/works skal returnere "works" hash? omtrent som det allerede er? i så fall ja. Hvis ikke må clustring skje ved at en slår opp på /api/works per verksuri og får anmeldelser under der.
Du tenker å ta med uri her? (authors)
ikke hvis det ikke er behov for det."books" vil si manifestasjoner?
ja, "manifestasjon" ser ikke bra ut i et api
Mener du at både /api/reviews og /api/works skal returnere "works" hash? omtrent som det allerede er? i så fall ja. > Hvis ikke må clustring skje ved at en slår opp på /api/works per verksuri og får anmeldelser under der.
Ah, ja vi kan jo godt flytte søk på forfatter+tittel til api/works? Gjerne det. Det er jo egentlig mest ryddig. I såfall er det ikke no behov får å pakke det inn i "works" hash slik. Søk på reviews gir kun reviews.
Du tenker å ta med uri her? (authors)
ikke hvis det ikke er behov for det.
Jeg synes alt som er interessant å bruke videre (dvs gjøres til linker) bør komme som uri+label, inkl forfatter. Og forfatternavn skal jo være klikkbart.
En liten ting:
"works" => [
<uri1> => { "title" => (title),
"originalTitle" => (originalTitle),Et verk har vel alltid bare originalTitle, og ingen andre title?
Det er manifestasjonene som kan ha en annen tittel.
Men hvis vi spør via ISBN på api/works så gir det jo mening. Men det er kanskje bedre å spør på ISBN via api/reviews - da får man jo alt man trenger.. eller hva tror du?
ah. har ikke fått mye tid til detta så langt, men gikk en runde i sola nå og :
/api/reviews må faktisk gi "works" likevel, fordi vi trenger paginering og sortering på anbefalinger, og ved oppslag på /api/works vil ikke offset limit osv på anbefalinger. gi mening.
altså:
beholder strukturen
"works" => [
<verksuri> => { "title => (title),
...,
reviews => [
<reviewuri> => {
"title" => (title),
men legger til urier og labels på alle steder det er naturlig.
samt gir samme struktur ved POST/PUT
enig?
så får heller /api/works være uavhengig og legge til reviews hvis vi lager et parameter for det
Jepp! Høres bra ut
Ang terminologi:
Hva med å bruke "edition" istedenfor book?
Work + edition høres bra ut sammen synes jeg.
Det er disse termen Open Library bruker f.eks.
Vi kan vel si oss fornøyd nå 😄