API-ändringar i version 1.5 [sv]
KulturNav version 1.5
I samband med version 1.5 av KulturNav så genomförs ett antal genomgripande förbättringar av tjänstens API.
Förenklad syntax för fältnamn
I KulturNav så har egenskaper/fältnamn tidigare angetts med värdesuffix - en ändelse som anger värdetyp - styrt av fältnamnsnotationen i sökindexet och eventuellt språk (för textegenskaper). I version 1.5 av API:et så har vi gjort att fältnamnen inte behöver en ändelse utan att enbart fältnamnen kan användas vid API-anrop.
- Referensvärden (uuid) anges enbart med fältnamnet, t ex superconcept.license
- Sant/falskt värde anges enbart med fältnamnet, t ex Superconcept.isPlaceHolder
- Strängvärden anges enbart med fältnamnet, t ex entity.code
- Textvärden anges enbart med fältnamnet, t ex entity.name. Språk hanteras nu i en separat parameter, se nedan.
- Datumvärden anges enbart med fältnamnet, t ex dataset.contentUpdatedAt
Tidigare syntax (KulturNav version 1.0):
- Referensvärden (uuid) angavs med "_r" efter fältnamnet, t ex superconcept.license_r
- Sant/falskt värde angavs med "_b" efter fältnamnet, t ex Superconcept.isPlaceHolder_b
- Strängvärden angavs med "_s" efter fältnamnet, t ex entity.code_s
- Textvärden med språk angavs med "_{språkkod}_t" efter fältnamnet, t ex entity.name_no_t (för språk norska)
- Datumvärden angavs med "_dt" efter fältnamnet, t ex dataset.contentUpdatedAt_dt
Den gamla syntaxen fungerar emellertid fortfarande i version 1.5.
Förenklad språkhantering
Språk anges i version 1.5 med med query-parameter ?lang={språk-kod} eller genom header Accept-Language: {språk}. Exempel: ?lang=sv eller header Accept-Language: sv.
Tidigare var språkhanteringen angiven på egenskapsnivå i samband med värdesuffix (se ovan).
Kompaktare JSON-struktur ger färre API-anrop
Den mest genomgripande förändringen av API:et märks i den JSON-struktur som skickas tillbaka från ett anrop. I version 1 har händelser/komplexa relationer, dvs egenskaper som relaterad information som innehåller flera egenskaper som rör tid, plats namn etc, levererats hanteras som referenser till egna unikt identifierade JSON-strukturer som hämtats via egna separata API-anrop. Det har t ex gällt händelserna för födelse och död för en person. I version 1.5 har dessa strukturer flyttats in till huvudposten (se person.birth nedan). Referenser/relationer mellan poster har kompletterats med information om refererad post (caption) i egenskapen displayValue, så att information kan visas om refererad post utan att den behöver slås upp i API:t (se person.gender nedan).
API-svar (delmängd) för version 1.5:
{
uuid: "37d98c32-e3cc-493c-ad49-051a407ff9f0",
entityType: "Person",
createdAt: "Apr 17, 2015 8:40:44 AM",
createdBy: "6a07513b-ea00-4905-a0e5-5a4146647b3e",
caption: {
no: "Nansen, Fridtjof (1861 - 1930)"
},
properties: {
...
person.birth: [{
valueType: "ENTITY",
value: {
uuid: "9476ef99-89c4-4d3d-bb39-ceecd6de6b57",
entityType: "Person.Birth",
inline: true,
caption: {},
properties: {
event.time: [{
valueType: "DATE",
value: "1861-Y"
}]
}
}
}],
person.death: [{
valueType: "ENTITY",
value: {
uuid: "e39aadc0-22ad-4bfd-8577-a64d73d22407",
entityType: "Person.Death",
inline: true,
caption: {},
properties: {
event.time: [{
valueType: "DATE",
value: "1930-Y"
}]
}
}
}],
person.gender: [{
valueType: "ENTITY_REFERENCE",
value: "86db2c30-24d9-11e2-81c1-0800200c9a66",
displayValue: {
no: "Mann",
sv: "Man",
en: "Man"
}
}]
...
}
}
Tidigare API-svar 1.x
Motsvarande element i ett API-svar från version 1.x ser ut så här (delmängd):
{
uuid: "37d98c32-e3cc-493c-ad49-051a407ff9f0",
entityType: "Person",
createdAt: "Apr 17, 2015 8:40:44 AM",
createdBy: "6a07513b-ea00-4905-a0e5-5a4146647b3e",
caption: {
no: "Nansen, Fridtjof (1861 - 1930)"
},
properties: {
...
person.birth: [{
valueType: "ENTITY_REFERENCE",
value: "9476ef99-89c4-4d3d-bb39-ceecd6de6b57"
}],
person.death: [{
valueType: "ENTITY_REFERENCE",
value: "e39aadc0-22ad-4bfd-8577-a64d73d22407"
}],
person.gender: [{
valueType: "ENTITY_REFERENCE",
value: "86db2c30-24d9-11e2-81c1-0800200c9a66"
}]
...
}
}
Utökad söksyntax
Ett antal nya möjligheter till sök introduceras i version 1.5:
OR-satser:
Sök med eller inom en specificerad egenskap:
/api/search/{egenskap}:{värde1}|{värde2}
/api/search/{egenskap}:{värde1} OR {värde2}
exempelvis:
entityType:Agent%7CNamedObject
entityType:Agent%20OR%20NamedObject
Sök efter hela fraser
/api/search/{egenskap}:"{sökfras}"
exempelvis
/api/search/text:"titeln hertig av"
Nya metoder
/api/version
Returnerar senaste version av API som används default.
Ändring av hantering av entity.list och mappar
Sök med entity.list
Mappar (entity.list) gör det nu möjligt att skapa kraftfulla grundfilter som t ex skapar urval av KulturNavsdata för specifika applikationer. Tidigare gav ett sök med entity.list:{uuid} alla entiteter direkt kopplade till en mapp (dvs både dataset och direktkopplade poster). I och med 1.5 så expanderas dataseten automatiskt så att deras innehåll finns med i mappen. Även dataseten returneras i svaret.
/api/search/entity.list:{uuid},{villkor},...
Returnerar listan/mappens totala, expanderade, innehåll av poster och dataset.
Använd entity.list som grundfilter för API-frågor
I en tillämpning vill du integrera mot olika uppsättningar dataset beroende av språk. Du vill t ex använda norska platsnamn i en norsk applikation och svenska i en svensk. Genom att samla önskade dataset i två mappar, norska platsdataset i mapp 1 och svenska platsdataset i mapp 2, kan du sedan bygga API-kopplingar som bara innehåller önskade urval vid API-anrop.
Dataset som tillhör en mapp expanderas till sitt innehåll av entiteter genom API-anropet.
Ändring av hantering av showIn i listor/mappar
Poster som visas i ett dataset (showIn) som läggs i en mapp finns nu med i returnerade data via /api/list{uuid}. Det betyder att en viss post kan finnas med i flera olika dataset, men att den fortfarande bara förvaltas av ett dataset.[sv]