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]