Förslag till nationell API-profil på Utvecklarportalen

@jonass annan vag tanke med DOI för dataset var att man skulle kunna ha dom som GITHUB subject (Wikidata egenskap P9100 - video tankar) för att göra lösningar med ett visst dataset mer findable

dvs. det skall vara enklare att hitta lösningar som skapats med visst dataset... känns lite som om du också varit inne på detta att det vore inte helt fel att tänka på samma sätt med olika API:er att man hittar en "konvention" kanske med GITHUB ämne så man enkelt hittar vilka lösningar som skapats med ett API.... så att andra kommer igång snabbt... leker en del på Kaggle och där är det självklart att koppla kod med dataset

Skrev lite om det på GITHUB community forum.... idag är det ofta forskare som är duktiga på att ange DOI för sina vetenskapliga papper och tillhörande dataset...

"How to Cite Datasets and Link to Publications"

jonor

@vesstrom Jag förstod utan större problem det övriga innehållet på sidan om hypermedia fram till det sista stycket. Där introduceras plötsligt begreppet "händelser" utan någon särskild motivering när man tidigare pratat om transaktioner, länkrelationer och typer.

Jag gick direkt in på sidan om hypermedia, så jag vet inte om man möjligen refererar underförstått till något som tas upp i andra delar av API-handledningen. Eller handlar det om att överföra befintliga RPC-liknande API:er till ett hypermedia-baserat gränssnitt?

De exempel som förekommer på sidan handlar om organisationer och kontotransaktioner, och där det gäller egna relationstyper anges svenska uttryck som "insättning" och "uttag" (är det realistiska exempel?).

Varför inte i så fall nämna "insättning, uttag och överföring" som exempel på domänspecifika typer då de redan tagits upp i ett sammanhang. Om nu detta också utgör ett exempel på vad man vill kalla "händelser" så kanske det uttrycket kan nämnas redan där det finns en kontext, t.ex. koppla det till ordet "transaktioner" som annars verkar användas för exemplen med "insättning", "uttag", "överföring", "edit", "replace", "delete".

"Olika typer av händelser" skulle kanske tydligare beskrivas av "representera domänspecifika händelseorienterade operationer som relationstyper/transaktioner" eller något liknande, och samtidigt referera till exemplen med kontotransaktioner (domänspecifika) och organisationer (standard).

Något som också är oklart är varför det är asterisker i relationstyperna, är det kanske ursprungligen märkspråk för fetstil i exemplet?

Inklistrat som vanlig inläggstext:

{"rel": " insättning", "href":"/konton/12345/insattning"},
{"rel": " uttag", "href":"/konton/12345/uttag"},
{"rel": " överföring", "href":"/konton/12345/overforing"}

{
     "kontonummer":"12345",
     "balans": 100.00,
     "_links":[
         {"rel": " **insättning**", "href":"/konton/12345/insattning"},
         {"rel": " **uttag**", "href":"/konton/12345/uttag"},
         {"rel": " **överföring**", "href":"/konton/12345/overforing"}
     ]
}

{
  "kontonummer":"12345",
  "balans": -25.00,
  "_links":[{
    "rel": "insättning",
    "href":"/konton/12345/insattning"
  }]
}

vesstrom

@jonor Uppskattar att du är engagerad och intresserad av vad vi tagit fram. Som sagt så finns det utrymme för förbättringar och delar som behöver förtydligas i texten. Dina åsikter är relevanta och vi ser gärna att du använder vår enkät som vi har för att mer formellt samla in feedback på REST API profilen.
Läs mer om detta här, https://www.digg.se/publicerat/remisser-och-yttranden/remisser-fran-digg/2020/lamna-synpunkter-pa-nationell-rest-api-profil

Tack

jonass

@salgo60-ej-aktiv För en handling, ett dokument, eller en forskningsartikel känns det naturligt att ha en unik global identifierare. Spontant tänker jag dock att ett DOI/sameAs attribut som i googles exempel gäller hela datasetet (en samling dokument, handlingar, forskningsartiklar), och kanske är en mer fråga för https://docs.dataportal.se/dcat/sv/. Dvs att objektet "datamängd" borde ha en identifierare. Hoppas att en expert på DCAT-AP-Se läser och tycker till.

Exempel från arbetsmarknaden när det är svårt att få dataproducenter att tagga sitt innehåll med en unik identifierare (jobbannonser förekommer ofta på många sajter).

Dubbletthantering: https://gitlab.com/arbetsformedlingen/joblinks/job_ad_hash/-/tree/develop

Tjänst: https://arbetsformedlingen.se/platsbanken/annonser?s=2

https://en.wikipedia.org/wiki/Jaccard_index och https://en.wikipedia.org/wiki/MinHash används för att identifiera informationsmängder som har stort överlapp.

Konsekvensen av att inte använda bra identifierare blir ju precis som du säger att det är svårt att i efterhand sortera upp informationen rätt.

jonor

@vesstrom Tack, jag ser gärna en öppen dialog då jag även är intresserad av att ta del av andras synpunkter och erfarenheter och följa diskussionen.

Dennis_Priskorn

@jonass sa i Förslag till nationell API-profil på Utvecklarportalen:

Exempel från arbetsmarknaden när det är svårt att få dataproducenter att tagga sitt innehåll med en unik identifierare (jobbannonser förekommer ofta på många sajter).

jag känner mig inte förvånad.

Dubbletthantering: https://gitlab.com/arbetsformedlingen/joblinks/job_ad_hash/-/tree/develop

Tjänst: https://arbetsformedlingen.se/platsbanken/annonser?s=2

https://en.wikipedia.org/wiki/Jaccard_index och https://en.wikipedia.org/wiki/MinHash används för att identifiera informationsmängder som har stort överlapp.

Intressant

Konsekvensen av att inte använda bra identifierare blir ju precis som du säger att det är svårt att i efterhand sortera upp informationen rätt.

Exakt och det är jobbigt för alla inblandade. Ett jobbuppslag är en historisk unik händelse. Den berättar mycket om vår samtid och om organisationen. Det är en värdefull datapunkt men behandlas att döma efter vad du skriver ovan styvmoderligt av alla inblandade...

Sparar riksarkivet alla annonser? Kan jag lätt kolla upp alla annonser SJ/Banverket hade ute i 1936? Är de bra kvalitet så jag kan köra NLP topic classification på dem? Kanske visualisera elektrifieringen av järnvägen med jobbannonserna som prism?

För att detta ska kunna göras så MÅSTE vi ha bra data med unika identifierare i grunden och gärna även grafdata som beskriver rollen de söker (tex backendutvecklare Q110245834 != frontendutvecklare Q54568999 != webbutvecklare Q6859454). För att detta ska funka måste vi ha in rollerna i en graf som vi kan peka på. Här har jag angett Wikidata QID men AF eller nån annan skulle lika väl kunna ha sin egen graf som beskriver varenda typ av jobb som förekommer eller har förekommit någonsin på svenska arbetsmarknaden.

Om ni vill ha hjälp att skapa en sådan graf så hojta till Era samarbetspartners och resten av världen kommer älska er! Inget har gjort det öppet än (@salgo60-ej-aktiv gissar att LinkedIn redan gör detta, men de håller korten tät till kroppen så det har inget allmänt värde för samhället utan syftar till vinstmaximering hos dem)

Jag skrev just riksarkivet
"Hej
Jag undrar om ni sparat jobbannonser från 1900-talet? Tex från banverket så jag kan se hur elektrifieringen påverkade jobbannonserna över tid?

Är de digitaliserade? Om inte, är det planerad? Vad är ETA på det arbetet i så fall?"

jonass

@dennis_priskorn https://data.arbetsformedlingen.se/annonser/historiska här kan annonser för åren 2006-2021 laddas ner.

Stefan Wallin

@kristine_ ni säger att ni vill ta emot synpunkter på ett strukturerat sätt. Men ändå vill ni ha en enkät med fritext. Varför publicerar ni inte API-profilen som ett gäng markdown-filer i ett publikt repo på exvis github eller gitlab så att kommentarer kan göras i kontext?

”Tala till de lärde på de lärdes vis och till apor på apors vis”.

Jag vill passa på att berömma att ni öppnar upp för feedback i en såpass tidig fas ändå!🤩

Kristine_

@stefan-wallin
Bra input, just idag använde vi inte Markdown men vi tar med oss frågan för hur vi långsiktigt ska arbeta med profilen och playbooken.

Hälsningar, Kristine

Peter_Bengtsson

Finns det en möjlighet att följa arbetet med API-profilen eller annars någon tidplan alternativt uppskattning av hur stora förändringar som förväntas som man kan ta del av?

Jordbruksverket är i ett läge där vi arbetar med att låta API:er ta en mer central roll i både applikations- och integrationsutveckling, vilket gör att behovet av förutsägbarhet kring API-profilen ökar då vi önskar utgå från den.

jenniferskoglund

@peter_bengtsson Vad kul att ni är intresserade och vill följa arbetet!

REST API-profilen har varit ute på remiss där personer som jobbar med utveckling av API:er har fått möjlighet att lämnar synpunkter. De inkomna synpunkterna hanteras och bearbetas nu av DIGG tillsammans med arbetsgruppen kring utvecklingen av REST API-profilen.

Vår plan är att releasa (publicera) och fastställa version 1.0 av REST-API Profilen inom ramen för Q2. På grund av att vi genomför en migrering av CMS (Content Management System) har vi svårt att lova någon specifik tidsplan och det gör det svårt att följa arbetet.

Om ni har mer specifika frågor kopplat till något specifikt område i profilen kontakta info@digg.se. Jordbruksverket har lämnat synpunkter på profilen, så det har vi med oss.

Läs mer om profilen på vår webbplats Utvecklarportalen, https://dev.dataportal.se/sv/rest-api--profil/.

Läs mer om synpunktsarbetet på vår webbplats, https://www.digg.se/publicerat/remisser-och-yttranden/remisser-fran-digg/2020/lamna-synpunkter-pa-nationell-rest-api-profil.

Observera att det inte längre går att skicka in synpunkter.

Peter_Bengtsson

@jenniferskoglund

Tackar för svaret! Q2 är ändå någonting att förhålla sig till.

Jag är en av de som var med och tog fram synpunkterna för Jordbruksverkets räkning, så skulle det uppstå några frågor är det bara att höra av sig.

jenniferskoglund

@Peter_Bengtsson Hej igen Peter, jag vill informera om att REST API-profilen har uppdaterats efter de synpunkter som kom in under den tidigare nämnda remissrundan. Sammanlagt kom det in mellan 500 till 1000 kommentarer från ett 60-tal aktörer och det är vi glada för Du hittar den första versionen på DIGG:s webbplats Utvecklarportalen, https://dev.dataportal.se/rest-api-profil

Stefan Wallin

@jenniferskoglund Hur vet vi vilka skillnader det är i 1.0 och den ursprungliga som ni bad om feedback på?

Observera att det inte längre går att skicka in synpunkter.

Varför kan man inte längre lämna synpunkter? Det känns inte så öppet i ärlighetens namn.

Stefan Wallin

@Stefan-Wallin Jag vill begära ut alla synpunkter som inkommit på API-profilen. Publicera gärna här i tråden i forumet eller på annat lämpligt digitalt sätt, så att vi kan få transparens för vilka som yttrat sig, vilka som till sist vägts in och vad som har prioriterats bort.

Tack på förhand

jenniferskoglund

@Stefan-Wallin vi har tagit emot din begäran. Eftersom vi som myndighet behöver förhålla oss till vissa lagar och regler måste vi pröva om efterfrågad handling kan lämnas ut. Vilken adress vill du att handlingarna ska skickas till? Återkom med adressen antigen via detta forum eller mejla in till info@digg.se.

jenniferskoglund

@Stefan-Wallin Inför fastställandet av v1.0.0 av profilen så har vi haft öppet för att lämna synpunkter i remissform. Vi kommer att fortsätta att ta emot synpunkter men via DIGG:s kundtjänst (info@digg.se eller +46 771 11 44 00). När vi gör sådant som ger en större påverkan (t.ex. major-uppgraderingar eller liknande) kommer vi att ta in synpunkter i remissform som vi gjorde nu.

Angående det som förändrats i profilen så har bland annat de olika kategorierna (15 st) i profilen fått sig ett lyft efter genomgång av alla de synpunkter som inkommit. En del kategorier har blivit lite mer uppdaterade än andra, men i stora drag handlar det om att tonaliteten i profilen har blivit genomarbetad på ett mer strukturerat och ändamålsenligt sätt. Detta utifrån uppsättningen identifierade SKALL/BÖR/KAN kravformuleringar som återkommer för varje kategori i profilen.

Att exakt peka på vad som förändras är svårt att redovisa och fyller inte ett direkt syfte eftersom vi hittills inte har haft en beständig version - det är den vi har skaffat oss nu. I framtiden kommer man att kunna jämföra olika versioner mellan varandra.

Som mycket annat är vi inte perfekta, men allteftersom kommer vi att utveckla hur vi jobbar samt verktyg och lösningar för det.

Stefan Wallin

@jenniferskoglund att det inte är versionshanterat från början innebär att ni själva inte har koll på vilka ändringar ni gör eller kan granska varandras arbete. Det känns ärligt talat inte bra!

Att det inte finns något syfte med att se skillnaden mellan versioner är ju trångsynt i bästa fall och huvudlöst i andra. NI har bett allmänheten om input. Allmänheten har spenderat massor med tid på att läsa, förstå och komma med inspel. Tror ni att de som redan är insatta kommer läsa igenom samma dokument igen pärm till pärm för att det är kul? För dessa personer hade naturligtvis en förändringslogg varit fördelaktig i tid sparad.

Jag kan inte förstå hur myndigheter i sverige som har så stark arkivarie-tradition inte automatiskt sätter versionsnummer och utgåvenummer och dokumentid på allting. Versionshantering bör inte vara nishat till digitaliseringen, men däremot har vi som kan digitalisering coolare verktyg för dokumenthanteringen. (ShareLatex, Github/Gitlab m.fl.). Hade jag varit jurist hade jag infört versionshanterad LaTeX på alla juridiska dokument!

jonor

Vilken version är det som ligger ute på den angivna länken? Jag undrar också vilka ändringar som har gjorts, jag kan inte se någon skillnad avseende de synpunkter jag lämnat själv.

(T.ex. ser det ut som någon klistrat in markdown som identifierare i exempelkod.)

Jag förstår inte riktigt vad som menas med den "första" versionen, är det den tidigare publicerade eller den nu uppdaterade?

@jenniferskoglund sa i Förslag till nationell API-profil på Utvecklarportalen:

@Peter_Bengtsson Hej igen Peter, jag vill informera om att REST API-profilen har uppdaterats efter de synpunkter som kom in under den tidigare nämnda remissrundan. Sammanlagt kom det in mellan 500 till 1000 kommentarer från ett 60-tal aktörer och det är vi glada för Du hittar den första versionen på DIGG:s webbplats Utvecklarportalen, https://dev.dataportal.se/rest-api-profil

Stefan Wallin

@jenniferskoglund eftersom ni inte själva vill lämna ut här på forumet men inte anser att det är problematiskt så har jag gjort en begäran via handlingar.se så nu kan alla som vill se remisssvaren.

https://handlingar.se/sv/request/alla_inkommna_api_synpunkter_pa#incoming-2439

Som jag förutspådde 2022-01-01 så är det grötigt att hänga med i vad som åsyftas av alla remissinstanser. Prova gärna Gitlab + Markdown-filer som ni kompilerar ihop till den profilsida ni har idag, då får ni både en vacker profilsida och data som data!