Arbetshypoteser för Elmarknadshubbens API - april 2019 Version 1.0
2 Introduktion till dokumentet och utvärderingen av API-prototypen Mål och syfte med dokumentet: Bakgrund: Målet med dokumentet är att tillgängliggöra information till systemleverantörer och marknadsaktörer om de API-egenskaper projektet har som arbetshypotes att använda i det fortsatta arbetet med framtagning av API:er för Elmarknadshubb. Syftet med informationen är att systemleverantörer och marknadsaktörer kan bilda sig en uppfattning om preliminära förutsättningar för integration med Elmarknadshubb. Projekt Elmarknadshubb arrangerade våren 2019 en utvärdering av API-prototypen och av arbetshypoteser för API:et. Målet med utvärderingen var att via återkopplingen få underlag för att anpassa API:ets egenskaper till de behov som finns hos aktörer och systemleverantörer. Deltagarna i utvärderingen var en undergrupp till Ediels-teknikgrupp (ETG) som bestod av systemleverantörer och aktörer, deltagandet var frivilligt. Målgruppen fick lämna återkoppling till projektet med hjälp av enkätsvar och i möten. För utvärderingen fick målgruppen tillfälligt tillgång till en prototypmiljö med API och stödverktyg, samt prototypversion av dokumentation. Prototypen bestod av API:er för mätvärdeshantering och marknadsprocessen start och slut av leverans. För mer information om syfte, mål och förutsättningar för utvärderingen se sidan 17 och 18. Förbehåll API-egenskaper beskrivna i det här dokumentet ska inte ses som fastslagna. API-egenskaper kan komma att ändras under det fortsatta arbetet.
Innehållsförteckning Sida Innehåll 2. Introduktion till dokumentet och utvärderingen av API-prototypen 4. Elmarknadshubben agerar master och kommunicerar både synkront och asynkront 5. Transaktioner utförs bara en gång, meddelanden sänds åtminstone en gång 6. Stöd för bibehållen ordning och bulköverföring av transaktioner där det finns behov 7. HTTP/1.1 för kommunikation med Elmarknadshubben 8. Transportprotokoll bygger på att aktören alltid anropar Elmarknadshubben 9. Beskrivning - Aktören sänder : HTTP-anrop (synkront svar) 10. Beskrivning - Aktören sänder : HTTP-anrop (asynkront svar) 11. Beskrivning - Hubben sänder : HTTP poll offset-baserat kvittens 12. Beskrivning - Hubben sänder : HTTP poll explicit kvittens 13. API:er för mätvärdeshantering utvärderades med RPC API-stil och poll-api 14. API:er för processen start och slut av leverans utvärderades med resursorienterad API-stil och poll-api 15. Meddelandeutformningen är baserad på Elmarknadshubbens kravmassa och med JSON format 16. API-specifikationen är baserad på Open API Specifikation (OAS3) 17. Utvärderingsresultatet var överlag positivt med värdefullt återkopplingsunderlag för det fortsatta arbetet 18. Syfte, mål och förutsättningar för utvärderingen 19. Översikt på aktiviteter och fokus under utvärderingen
4 Elmarknadshubben agerar master och kommunicerar både synkront och asynkront Hubben agerar master och koordinator Med introduktionen av Elmarknadshubben delegerar aktörerna ansvaret för att hålla det globala tillståndet på elmarknaden i enlighet med gällande affärsregler till Elmarknadshubben. Initierande aktör begär tillståndsändring och får kvittens att Elmarknadshubben har genomfört förändringen Elmarknadshubben orkestrerar processen genom att notifiera påverkade aktörer om genomförda tillståndsändringar Påverkade aktörer uppdaterar sitt eget tillstånd så snart som möjligt efter men ska ej kvittera på affärsnivå Realisering med synkron och asynkron kommunikation Elmarknadshubbens API:er är i grunden synkrona REST/RPC-anrop, men utgående trafik initierad av Elmarknadshubben är alltid asynkron för att minska kraven på tillgänglighet / upptid för aktörerna Synkron för att kunna ge direkta svar utan extra kanal Utgående meddelanden initierade av Elmarknadshubb är alltid asynkrona. Aktörens API-klient anropar API och hämtar meddelanden (poll) från en kö i Elmarknadshubben. Projektet överväger metod för asynkrona anrop där det finns behov av bulkuppladdning av transaktioner.
5 Transaktioner utförs bara en gång, meddelanden sänds åtminstone en gång Meddelanden sänds åtminstone en gång För att kunna hantera otillförlitliga nätverk och förlorade kvittenser måste transaktioner kunna sändas om utan oönskade sidoeffekter Meddelanden kan levereras flera gånger Meddelanden ska sändas om då kvittens saknas Meddelande som redan har hanterats ska ge samma resultat** Transaktioner utförs bara en gång Då meddelanden kan sändas om är det viktigt att affärstransaktioner inte utförs mer än en gång Varje transaktion har ett för aktören unikt id Hubben använder transaktions-id för att avgöra om en operation / transaktion är utförd eller inte (idempotens) Aktörer tillser att transaktioner som skickas flera gånger hanteras utan felmeddelanden och sidoeffekter ** Finns fall då detta inte är möjligt
6 Stöd för bibehållen ordning och bulköverföring av transaktioner där det finns behov Transaktioners ordning är ibland viktig När flera operationer utförs mot samma underliggande resurs kan ordningen de utförs i vara av vikt. Det är dock sällan samma resurs uppdateras flera gånger i snabb följd. I de fall ordning har bedömts ha betydelse kommer det indikeras i API:ets dokumentation. Det är upp till aktörerna att anropa hubben i affärsordning då det har betydelse. När Elmarknadshubben tillhandahåller meddelanden där ordningen är av vikt bevaras ordningen. Bulköverföring av transaktioner i undantagsfall där det finns behov Utgångspunkten för API-design är en transaktion, ett meddelande. I vissa fall kan API designas med stöd för bulköverföring för att öka kanaleffektiviteten: Vid design av API för överföring av stora transaktionsmängder till Elmarknadshubben. Vid design av API där Elmarknadshubben tillhandahåller meddelande ifrån poll-api.
7 HTTP/1.1 för kommunikation med Elmarknadshubben Arbetshypotes att använda HTTP/1.1 för aktörskommunikation med Elmarknadshubben och överväga stöd för bulköverföring av transaktioner för API:er med behov av effektivt kanalutnyttjande. Motivering: HTTP/1.1 är moget och stabilt protokoll, det finns ett utbrett kompetens- och systemstöd. Överväganden under API-utvärderingen (huvudsakliga) Utvärderingsgruppens syn på stöd för alternativa protokoll till HTTP/1.1 eller behovet av ett alternativt protokoll till HTTP. Protokollets kanaleffektivitet för överföring av stora mängder av små transaktioner. Inte behov av realtidsöverföring av transaktioner som initierats av Elmarknadshubben, vilket inte förutsätter ett strömmande protokoll. Alternativ som diskuterats under utvärderingen men som avförts då HTTP/1.1 bedömts uppfylla kraven, ha brett stöd och vara enklare att hantera. AMQP 1.0 var en av projektets arbetshypoteser som komplement till HTTP. HTTP/2 var en av projektets arbetshypotes som alternativ till HTTP/1.1. sftp togs upp som förslag för överföring av stora filer. Websockets togs upp som förslag på protokoll för framtiden för att strömma data ifrån hubben. ECP/Mades togs upp som förslag för överföring då vissa aktörer använder det eller kommer att använda det.
8 Transportprotokoll bygger på att aktören alltid anropar Elmarknadshubben Under API-utvärderingen av prototypen utvärderades olika transportprotokoll (kommunikationsmönster). På kommande sidor går det att se en översikt för respektive transportprotokoll som varit med i utvärderingen. Aktören sänder : HTTP-anrop (synkront svar). Aktören sänder : HTTP-anrop (asynkront svar) kombination av HTTP-anrop och HTTP poll. Hubben sänder : HTTP poll offset-baserat kvittens. Hubben sänder : HTTP poll explicit kvittens.
9 Beskrivning - Aktören sänder : HTTP-anrop (synkront svar) 1. Aktören gör ett anrop till API-resursen på Elmarknadshubben i enlighet med API-specifikation. URL:en kan vara utformad med en resursorienterad stil (dynamisk URL) eller RPC/Metod stil (statisk URL) 2. Elmarknadshubben validerar anropet och behandlar förfrågan och skickar svar på samma förbindelse. Anropet ska alltid returnera en statuskod, med eller utan svarsmeddelande i enlighet med API-specifikationen. 3. Aktören har ansvar tills en positiv bekräftelse (HTTP status 200-familjen) mottagits från Elmarknadshubben.
10 Beskrivning - Aktören sänder : HTTP-anrop (asynkront svar) 1. Aktören gör ett anrop till API-resursen på Elmarknadshubben i enlighet med API-specifikation. 2. Elmarknadshubben svarar med HTTP status accepted (202) eller felkod (400, 500) 3. Aktören anropar (pollar) en API-resurs som exponerar en kö där svar till det ursprungliga anropet kommer. Se även beskrivning av transportprotokoll för HTTP poll på nästkommande sidor. Asynkront svar
11 Beskrivning - Hubben sänder : HTTP poll offset-baserat kvittens 1. Aktören anropar (pollar) en API-resurs som exponerar en kö med färdiga meddelanden. Anropet består av: Ett aktörs ID (actorid), En referens till senaste lästa meddelandet (offset), eller 0 om första gången. En valfri parameter om hur många meddelanden som ska hämtas (limit), anges inget hämtas 1 meddelande. 2. Elmarknadshubben validerar anropet och returnerar en lista med meddelanden från kön, upp till givet antal (limit). Meddelanden omsluts med en liststruktur med en identifierare event token för varje meddelande 3. Aktören bearbetar meddelandena i den ordning som de mottagits i liststrukturen och sparar ned event token från det senaste bearbetade meddelandet för användning som offset i nästkommande anrop. Hubben har en gräns för max antal meddelanden som går att hämta per anrop t.ex. 100, 1000. Hubben tar bort meddelanden efter en bestämd tid, tiden är ej ännu bestämd, gissningsvis några dagar. Eventuellt tas meddelanden bort först då hubben har registrerat en hämtning med ett senare offset.
12 Beskrivning - Hubben sänder : HTTP poll explicit kvittens 1. Aktören anropar (pollar) en API-resurs som exponerar en kö med färdiga meddelanden. Anropet består av: Ett aktörs ID (actorid), En valfri parameter om hur många meddelanden som ska hämtas (limit), anges inget hämtas 1 meddelande. 2. Elmarknadshubben returnerar en lista med okvitterade meddelanden som finns på kön upp till givet antal (limit). Meddelanden omsluts med en liststruktur med en identifierare event token för varje meddelande 3. Aktören bearbetar meddelandena i den ordning som de mottagits i eventstrukturen. 4. Aktören kvitterar hämtade meddelanden genom att anropa API:et med en lista av event token. 5. Elmarknadshubben markerar kvitterade meddelanden som kvitterat.
13 API:er för mätvärdeshantering utvärderades med RPC API-stil och poll-api API:er för mätvärdeshantering utvärderades med RPC API-stil, det innebar en statisk URL med ett metodnamn, t.ex. registermeter-value. API:et för att hämta mätvärden utvärderades med det offset-baserat poll-api-mönstret. Det explicita kvittensmönstret fanns med i utvärderingen för teoretisk utvärdering i form av API-specifikation. Bild tagen ur API-specifikationen (swagger)
14 API:er för processen start och slut av leverans utvärderades med resursorienterad API-stil och poll-api API:er för processen start och slut av leverans utvärderades med resursorienterad API-stil med anpassat metodnamn, detta kan ses som en hybrid mellan API-stilen REST och RPC. Exempel: POST /customer-and-contracts/v1/accounting-points/{accountingpointid}/deliveries/start {accountingpointid} = resurs för avräkningsobjekt, del av den för prototypen antagna naturliga nyckeln. /start = anpassad metodnamn. Istället för standardmetoderna i HTTP som vedertaget används för REST. Arbetshypotesen för prototypen var att identifiera en leverans med naturlig nyckel istället för syntetisk nyckel så som ett ärendenummer. Slutsatsen blev att nyckeln för leverans ska analyseras ytterligare. Bild tagen ur API-specifikationen (swagger)
15 Meddelandeutformningen är baserad på Elmarknadshubbens kravmassa och med JSON format Meddelandeutformningen för API är baserad på Elmarknadshubbens kravmassa och informationsmodell och APIdesignprinciper, i syfte att få enhetlig utformning baserad på domänspråk och faktiskt behov. Meddelandeformatet är JSON (Javascript Object Notation).
16 API-specifikationen är baserad på Open API Specifikation (OAS3) Arbetshypotesen är att använda Open API Specification (OAS), även kallad swagger. OAS beskriver API-egenskaper och meddelandemodeller. Prototypen har använt OAS version 3.0.
17 Utvärderingsresultatet var överlag positivt med värdefullt återkopplingsunderlag för det fortsatta arbetet Överlag indikerade återkopplingen från målgruppen att arbetshypoteserna uppfattas bra, detta genom att medelpoängsnivån på enkätfrågorna i de flesta fall varit på den övre positiva delen av skalan. Projektet fick en mängd värdefull återkoppling utöver det projektet efterfrågat, t.ex. kring önskad funktionalitet, optimering, hittade buggar, etc. Återkopplingen på API-prototypen blir ett underlag till det fortsatta arbetet med att förbättra API:ets egenskaper inför nästkommande fas.
18 Syfte, mål och förutsättningar för utvärderingen Syftet var att få återkoppling på API:ets egenskaper utifrån aktörernas och systemleverantörernas perspektiv. Målet var att via återkopplingen få underlag för att anpassa API:ets egenskaper till de behov som finns hos aktörer och systemleverantörer. Erfarenheten visar på att det är vid verklig integration med ett API som det blir konkret hur väl API:ets egenskaper adresserar API-konsumentens behov. Förutsättningen var att aktören som deltog i utvärderingen utvärderade API:et med valfri teknik allt ifrån en enkel API-testklient (t ex SoapUI) till utveckling av egen API-klient med eller utan integration med den egna testmiljön. API-prototypen var medvetet implementerad med begränsad funktionalitet med fokus på att möjliggöra olika utvärderingar. Tanken var att via Fail-fast kvalitetssäkra arkitektoniska och tekniska hypoteser tidigt med hjälp av målgruppen. Detta innan mycket tid investerats i en API-implementation som potentiellt har suboptimala egenskaper för APIkonsumenterna. Då det är en prototyp med begränsad funktionalitet, innebar det att det var de tänkta egenskaperna att utvärdera i sådant fall en funktion var begränsad. Efter varje utvärderingsaktivitet fick deltagarna i utvärderingen bedöma svårighetsgraden eller stödet för t.ex. en teknisk aspekt genom att besvara enkätfrågor och lämna egen återkoppling på prototypen. Enkätsvaren med betygsättning och åsikter gicks igenom i ett uppföljningsmöte efter varje utvärdering. Återkopplingen till projektet på prototypen var rådgivande men inte styrande.
19 Översikt på aktiviteter och fokus under utvärderingen Uppstart & information Återkoppling, frågor & svar Uppstart utvärdering Utvärdering API för mätvärden Utvärdering API för start & slut av leverans & sammanställning 2019 Jan Feb Mar Utvärdering 1 Utvärdering 2 Apr Utvärderingsfokus Till möte Baserat på Arbetshypoteser Kommunikation Egen återkoppling API-egenskaper för registrera & hämta mätvärden API-stil RPC (statisk API-URL) Poll-API, bulköverföring mätvärdesevents API- Specifikation & prototyp av BRS-dokumentation Egen återkoppling API-egenskaper för start & slut av leverans API-stil resursorienterad (dynamisk API-URL) Poll-API, bulköverföring olika leverans -events API- Specifikation & prototyp av BRS-dokumentation Egen återkoppling Möte 2 - återkoppling & senare Möte 4 - Utvärdering API för mätvärden Möte 5 Utvärdering API för start och slut för leverans & sammanställning Beskrivning i den här presentationen Utvärderingsmiljön API-specifikation Prototyp simulator API Tillhandahållen dokumentation Utvärderingsmiljön API-specifikation Prototyp simulator API Tillhandahållen dokumentation