Jobindsats – Detaljeret design – API
- Bjarne Hansen (Edora)
Indholdsfortegnelse
Formål
Dette dokument har til formål at beskrive JSON strukturen, der udstilles af Jobindsats datamodel API’et. Der henvises til Jobindsats – Integrationsdesign for en beskrivelse af grænsefladerne og til Jobindsats - Logisk datamodelarchived for en detaljeret beskrivelse af reglerne for udtræk af data fra metadatamodellen.
Målgruppe
Dokumentet er tiltænkt udviklere eller andre tekniske stakeholders med et ønske om at forstå JSON opbygningen af returkaldet fra Jobindsats datamodel API’et.
Endpoints JSON-struktur
Der findes tre endpoints til Jobindsats 3.0 API’et som beskrevet i tabellen nedenfor. De efterfølgende tre afsnit beskriver JSON strukturen for det returobjekt, der returneres fra API’et ved efterspørgsel.
Endpoint | Http request | Input | Beskrivelse |
/Api/DatabankElementPage | GET | maaling_id
force
| Anvendes til at hente og vise fordelingsvariablerne i front-enden på målingssiden. Tager et enkelt maaling_id som input. Force benyttes til at sikre der laves et nyt objekt og uanset om der findes et i cachen. |
/Api/DatabankTemaPage | GET | maaling_id
force
| Anvendes til at hente og vise målingerne med metadata på overskrift-niveau på målings-vælger siden. Tager et enkelt maaling_id som input. Force benyttes til at sikre der laves et nyt objekt og uanset om der findes et i cachen. |
/Api/getdata | POST | @cube = 'y11c02' @period = '{"period":["2018M01"]}' @area = '{"area":["Rebild"]}' @measure = '{"measure":["membc01_2"]}' @dimension = '{"dimension":["_alder_5i40s","_tilb_2ptv"]}' @dim1 = '{"_alder_5i40s":["40+ år"]}' @dim2 = '{"_tilb_2ptv":["Tilbud i alt"]}'
| Anvendes til at hente og vise målingsdata i front-enden Tager målingsdata som input ud fra de valgte værdier præsenteret på målingssiden i et forudbestemt format defineret af den stored procedure, der returnere data.
|
/Api/BuildCache | GET | ingen input | Anvendes til at bygge/genbygge cachen for både tema sider samt databank element sider. |
/Api/TestCache | Get | maaling_id
| Anvendes til at teste indholdet af cachen. Der returneres altid et count af entries i cachen. Hvis der ikke gives et maalings id med vil der komme en liste af alle de keys som er i cachen. Hvis der givet maalings id vil de objekter som relaterer sig til dette blive returneret Al returneret data skrives til loggen som info |
JSON: Api/DatabankElementPage
{ "maalingId": "string", "cubeId": "string", "footnote": "string", "dataSourceTexts": [ "string" ], "updateInfo": { "lastUpdate": "Datetime", "nextUpdate": "Datetime" }, "periodes": [ { "displayName": "string", "year": "int", "period": "string", "periodType": "string", "taller": "int" } ], "mGroups": [ { "displayName": "string", "footnote": "string", "mgroupID": "string", "mgroupCount": "int" } ], "maalingHierarchiesContainer": [ { "displayName": "string", "footnote": "string", "hierarchyId": "string", "dimensionId": "string", "required": "boolean", "selectable": "boolean", "hierarchies": [ { "hrchyId": "string", "name": "string", "children": [ null ] } ] } ] } |
JSON: API/DatabankTemaPage
{ "maalingId": "string", "updateInfo": { "lastUpdate": "Datetime", "nextUpdate": "Datetime" }, "period": { "firstAndLast": [ "string" ], "types": [ "string" ] }, "updateFreq": "string", "area": { "wholeCountry": "boolean", "areas": [ "string" ] }, "mGroups": [ "string" ], "dimensions": [ "string" ] } |
JSON: API/getdata
POST objekt:
{ "DataParameterObject": { "type": "object", "properties": { "cube": { "type": "string", "description": "The Cube for which the maaling is located, can be any string", "nullable": true }, "period": { "type": "string", "description": "Period - must be valid Json or null", "nullable": true }, "area": { "type": "string", "description": "Area - must be valid Json or null", "nullable": true }, "measure": { "type": "string", "description": "Measure - must be valid Json or null", "nullable": true }, "dimension": { "type": "string", "description": "Dimension - must be valid Json or null", "nullable": true }, "dim1": { "type": "string", "description": "Dim1 - must be valid Json or null", "nullable": true }, "dim2": { "type": "string", "description": "Dim2 - must be valid Json or null", "nullable": true }, "dim3": { "type": "string", "description": "Dim3 - must be valid Json or null", "nullable": true }, "dim4": { "type": "string", "description": "Dim4 - must be valid Json or null", "nullable": true }, "dim5": { "type": "string", "description": "Dim5 - must be valid Json or null", "nullable": true }, "dim6": { "type": "string", "description": "Dim6 - must be valid Json or null", "nullable": true }, "dim7": { "type": "string", "description": "Dim7 - must be valid Json or null", "nullable": true }, "dim8": { "type": "string", "description": "Dim8 - must be valid Json or null", "nullable": true } } } } |
Responseobjekt:
Caching
For at optimere hastighed på loads fra metadatadatabasen (og views) er der oprettet caching på data til databank temasider samt elementsider.
Caching er sat op til at blive bygget første gang ved startup og fungerer ved at der laves et http get kald til endpointet: ”/Api/BuildCache”. I dette kald forsøges det at lave cachede dataobjekter fra alle” maaling_id”’er i metadatadabasen.
Når et nyt objekt oprettes i databasen, sættes dets expiration tid til midnat (kl. 0.00) dagen efter, et cachet objekt kan altså højest have en levetid på 24 timer.
De to api endpoints ”/Api/DatabankTemaPage” samt ”/Api/DatabankElementPage” benytter som standard altid cachede data hvis tilgængeligt. Skulle der blive efterspurgt et ”maaling_id” som ikke findes i cachen forsøges der at blive lavet et nyt dataobjekt fra databasen som herefter bliver gemt i cachen. Hvis der ikke kan laves et objekt (grundet fejl eller manglende data) gemmes intet i cachen. Hvis det ønskes ikke at benytte det cachede data (fx grundet opdateret datagrundlag) kan de to endpoints kaldes med force=true, dette vil tvinge generering af et nyt objekt som herefter gemmes i cachen og overskriver det evt. gamle objekt.
Da de cachede elementer udløber til midnat, skal endpointet ”/Api/BuildCache” kaldes til dette tidspunkt for at sikre tilgængelige cachede elementer. Dette gøres i ”Startup.cs”, i funktionen ”CreateCache”, hvor der laves en instance af ”MyScheduler”. Denne kaldes med ”MyScheduler.IntervalInHours(0, 0, 24)” hvilket læses som ”0. time”, ”0. minut” og med et interval på 24 timer, altså en trigger klokken 0.00 hver 24. time.
For at kunne lave et http get kald til det rigtige endpoint er den relevante url gemt i ”appsettings.json” som ”BuildCacheURL” under connectionstrings. Dette muliggør at have forskellige URL’er til forskellige miljøer. I development er der som standard sat: "http://localhost:49198/Api/BuildCache".
Logning
For de forskellige endpoints er der logning ved bl.a. fejl og andre uregelmæssigheder. Loggen kan findes i APIprojektet i mappen logs: ”Jobindsats.Datamart.Service\Jobindsats.Datamart.Service.API\logs”. Der bliver dannet en ny log hvor dag med navngivningen: ” log-YYYYMMDD.txt”.
Api/DatabankElementPage
Hvis der opstår en generel fejl, gribes denne og logges med teksten: Error occurred in DatabankElementPage for ”målingsID”. ”Denne efterfølges af fejlen
Hvis der opstår en fejl i processen med at fortolke de hierarkier som benyttes til visning. Hvis der er tale om fejl som automatisk kan rettes (se eksempel på fejl i Jobindsats - Logisk datamodelarchived) vil der i logen indføres en tekst som denne:
2021-12-22 15:07:46.453 +01:00 [INF] Parent with hierarchy id /50/ were automatically found for child with hierarchy id /50/1000/2/ System.Collections.Generic.KeyNotFoundException: The given key '/50/1000/' was not present in the dictionary. at System.Collections.Generic.Dictionary`2.get_Item(TKey key) at Jobindsats.Datamart.Service.API.Controllers.ApiController.AddChildNodesToParents(IEnumerable`1 hierarchy) in C:\Users\rvso\source\repos\SFARJOBIN\Jobindsats.Datamart.Service\Jobindsats.Datamart.Service.API\Controllers\ApiController.cs:line 408 |
Hvis der optræder en fejl som ikke automatisk kan rettes gemmes denne besked i loggen:
”Error occurred when calling Hierarchies”. Denne efterfølges af fejlen. Hvis dette sker, vil der blive sendt et tomt hierarki op så det er muligt for slutbrugen at se og anvende de hierarkier som ikke fejlede i frontenden.
API/DatabankTemaPage
Hvis der opstår en generel fejl, gribes denne og logges med teksten: Error occurred in DatabankTemaPage for ”målingsID”. Denne tekst efterfølges af fejlen.
API/getdata
2021-12-22 14:57:17.658 +01:00 [INF] No data found for params: { "Cube": "y30e21", "Period": "{\"period\":[\"2017M01\"]}", "Area": "{\"area\":[\"Hele landet\",\"RAR Hovedstaden\",\"Albertslund\",\"Allerød\",\"Ballerup\",\"Brøndby\",\"Dragør\",\"Egedal\",\"Fredensborg\",\"Frederiksberg\",\"Frederikssund\",\"Furesø\",\"Gentofte\",\"Gladsaxe\",\"Glostrup\",\"Gribskov\",\"Halsnæs\",\"Helsingør\",\"Herlev\",\"Hillerød\",\"Hvidovre\",\"Høje-Taastrup\",\"Hørsholm\",\"Ishøj\",\"København\",\"Lyngby-Taarbæk\",\"Rudersdal\",\"Rødovre\",\"Tårnby\",\"Vallensbæk\",\"RAR Sjælland\",\"Faxe\",\"Greve\",\"Guldborgsund\",\"Holbæk\",\"Kalundborg\",\"Køge\",\"Lejre\",\"Lolland\",\"Næstved\",\"Odsherred\",\"Ringsted\",\"Roskilde\",\"Slagelse\",\"Solrød\",\"Sorø\",\"Stevns\",\"Vordingborg\",\"RAR Bornholm\",\"Bornholm\",\"RAR Fyn\",\"Assens\",\"Faaborg-Midtfyn\",\"Kerteminde\",\"Langeland\",\"Nordfyns\",\"Nyborg\",\"Odense\",\"Svendborg\",\"Ærø\",\"RAR Sydjylland\",\"Billund\",\"Esbjerg\",\"Fanø\",\"Fredericia\",\"Haderslev\",\"Kolding\",\"Middelfart\",\"Sønderborg\",\"Tønder\",\"Varde\",\"Vejen\",\"Vejle\",\"Aabenraa\",\"RAR Østjylland\",\"Favrskov\",\"Hedensted\",\"Horsens\",\"Norddjurs\",\"Odder\",\"Randers\",\"Samsø\",\"Silkeborg\",\"Skanderborg\",\"Syddjurs\",\"Viborg\",\"Aarhus\",\"RAR Vestjylland\",\"Herning\",\"Holstebro\",\"Ikast-Brande\",\"Lemvig\",\"Ringkøbing-Skjern\",\"Skive\",\"Struer\",\"RAR Nordjylland\",\"Brønderslev\",\"Frederikshavn\",\"Hjørring\",\"Jammerbugt\",\"Læsø\",\"Mariagerfjord\",\"Morsø\",\"Rebild\",\"Thisted\",\"Vesthimmerlands\",\"Aalborg\"]}", "Measure": "{\"measure\":[\"mgrp_e21_4\"]}", "Dimension": "{\"dimension\":[\"_varig_y30e21\",\"_ygrp_e21\"]}", "Dim1": "{\"_varig_y30e21\":[\"12 måneder og derover\"]}", "Dim2": "{\"_ygrp_e21\":[\"Overgangsydelsesmodtagere uden for program\"]}", "Dim3": null, "Dim4": null, "Dim5": null, "Dim6": null, "Dim7": null, "Dim8": null } |
Hvis der returneres et data objekt men dette er tomt (fx hvis brugeren har valgt for specifikke valg), gemmes data parameterobjektet på JSON form således:
Hvis der opstår en fejl, og der dermed aldrig returneres et data objekt vil en lignede besked gemmes i lokken dog med første linje ændret til:
2021-12-22 14:57:17.658 +01:00 [WRN] Error occurred with params: |
|---|
Desuden vil der over fejlen stå at fejlen opstod i getData funktionen: ”Error occurred in GetData", efterfulgt af den specifikke fejlmeddelelse.