Skolplattformens API:er lämnas inte ut – finns ingen dokumentation

Ser egentligen inget problem med det om beställaren köper hela lösningen inkl. källkoden(d.v.s. beställaren äger den) ifrån t.ex. ett multinationellt företag med säte i bl.a. Sverige och sedan väljer att offentliggöra den under en valfri licens.

När kunden fick räkningen på det så var det ingen som ville kännas vid fakturan(dom bollade bara runt den inom den statliga institutionen). Slutade istället med halva priset så att vi fortsatte att äga lösningen och dom fick istället en nyttjandelicens men ej tillgång till någon källkod.

OK, så hela ditt resonemang bygger på att det inte tar speciellt lång tid att skriva dokumentation för att man redan har skrivit den.

Jag jobbar mest agilt nu för tiden, så det blir mest user stories och arkitektur i början. Det kan utvecklas rätt mycket med tiden. Då kan det bli jobbigt att sitta och omarbeta dokumentation hela tiden.

C# XML documentation är rätt trevligt, men om man inte har alltför komplicerade API:er kan det bli litet mycket ///<param name="user">A user.</param>. Sedan beror det ju litet på vilket slags projekt det är och vilken publik det har. Har man inte en miljon smör-och-bröd endpoints är det ju litet lättare och viktigare med dokumentation.

Jepp. Dokumentationen skall vara klar innan skarp driftsättning. Har man inte det så kanske man inte skall driftsätta något skarpt för det första. Låter i min värld om man gör det ändå så bedriver man en Kalle Anka organisation. Vilket jag anser mig se tydliga tecken på gällande det som tråden handlar om.

Det gör dom också sedan förra året, även om han egentligen gjorde så redan sedan år 2017 när vi tillsammans jobbade på ett litet projekt som inte är i samma storlek som det som omnämns i tråden men det var just ett API(brygga kallar vi den) mot hårdvara åt en statlig institution. Vi hade regelbunden testning och kontakt med beställarens tekniska representant. Nu var det troligtvis inte lika mycket att dokumentera för vår del(max 20 funktioner som exponerades, om ens det) som det som tråden handlar, men jag anser att samma princip skall tillämpas på så väl små som stora projekt. Jag anser att det är viktigare i större projekt än små att man börjar tidigt med dokumentationen.

Måste varit något sådant, för det såg riktig coolt ut för en som mig som har stannat på 90-talet, att han kunde anropa/se "hjälpen" direkt i källkoden för själva testprogrammet(som agerade kundens miljö) trots att bryggan(DLL fil som WFC tror jag?) var kompilerad och klar.

Ingen ville trycka på knappen "Betala".
Och den som hade godkänt beställningen hade inte förstått vad det skulle kosta(det gick enligt löpanderäkningsprincipen).

Vi lämnade aldrig ut källkoder innan full betalning anlänt, oavsett projekt.
Kunder kunde komma till kontoret i Lund(före Corona åren) för att se hur några sidor källkoder såg ut på några skärmar.

Efter lite snack så blev det halva priset(inga miljonbelopp men i alla fall en sexsiffrig summa) och vi fick inte vad vi hade räknat med men tillräckligt för att täcka våra kostnader och få en liten vinst. Det hade ändå inte gått att sälja den till någon annan så det var ett s.k one-off projekt där vi ville ha enligt överenskommelse(löpande) eftersom den var väldigt specifik för denna kund(dom bestämde i princip precis hur dom skulle vilja att anropen skulle formuleras ifrån deras miljö).

Om man tycker att det är ok att det ska ta så lång tid, då bör man nog se sig efter ett annat jobb.
Jag har inga problem att prata med HR om tjänstefel i detta fall .

I Malmö, men förvisso statlig och inte kommunal förvaltning.

Vi lever nog i helt olika världar, du och jag. Det låter på dig som om du jobbar med vattenfallsutveckling, med klara direktiv över hur allt ska fungera in i minsta detalj från första början och överlämningar när allt ska vara klart. I min drömvärld hade jag kört devops fullt ut med deploy varje dag, men det är tyvärr inte möjligt i dagsläget. Jag kan inte komma ihåg någon brydde sig om dokumentation annat än som något som skulle kontrolleras att den fanns för att leveransen skulle godkännas, och en skarp driftsättning är för mig startskottet för den riktiga utvecklingen.

Sägas bör dock att jag gör ingenting som kräver användardokumentation och lägger en del tid på datakontrakt.

Jag antar du inte jobbar med utveckling och inte vet vad en API-dokumentation innebär. Nu vet jag förvisso inte hur omfattande Skolplattformens API är, men jag antar att för en miljard så har de fått mer än en handfull endpoints. Även fast det inte verkar fungera så bra så är det inget hobbyprojekt det handlar om. Hade du läst min tidigare väldigt grova uppskattning på hur lång tid det skulle ta att dokumentera hade du kanske förstått hur det lätt kan gå en vecka på att dokumentera att API.

Det är ju klart att det finns dokumentation, hur skulle de annars kunna utveckla mot sitt eget API. Men att göra denna dokumentation tillgänglig till externa utvecklare är någon helt annat. Då kanske API:et behöver dokumenteras på ett lite annorlunda sätt, samt att man måste bygga upp en infrastruktur runt själva API:et t.ex. för att utvecklare ska kunna registrera sig och generera ett eget applikations ID. Sedan handlar det ju också om vem som ska ta kostnaden när externa applikationer anropar ett API som de själva inte hostar. För att inte tala om säkerheten. Om vem som helst har tillgång till ett API så har man inte längre full koll på var datat tar vägen.

Det är lite roligt att läsa en del av kommentarerna, för det blir så uppenbart att många inte har en aning om vad dom pratar om. Allt är "skrämmande" och "chefer är dumma i huvudet som inte begriper någon ting". Om om ni nu är så smarta själv så gissar jag att det finns massor av jobb åt er. Bara ni utbildar er först.

Systemet är nog inte rocket science, direkt, och det inbegriper nog mest fattbara begrepp som "elev", "schema", "kurs" o.s.v. Ett sådant API är inte så svårt att konsumera. Har man dessutom tillgång till källkoden, som jag antar att utvecklarna har, så är det nästan bättre än dokumentation, för då kan man läsa sig till hur det fungerar. Sedan kan ju utvecklarna kommunicera med varandra också.

Jag har själv (på fritiden) skrivit enklare rest-apier i nodejs för att hämta data ifrån databaser och skicka till mina små enheter jag satt ihop här hemma, så har ett litet hum på amatörnivå.
Och jag dokumenterar mina funktioner med visual studio codes kommentarer, så man ska ha ett hum ett år senare när man vill lägga till något.

Jag är ganska säker på att all dokumentation finns hos utvecklarna, men av olika skäl vill man bara inte lämna ut dessa och skyller då på detta.
Om inte, så bör man väl fundera på att spendera nästa miljard på ett lean-projekt.

https://youtu.be/DwTvj3KDTgE

Om man inte lyssnar på honom kommer man vakna upp försent...

Sista svaret från mig i ämnet är att Henrik säger sanningen (inga konspirationsteorier) om Sveriges politiska läge utan att ta parti för något politiskt parti.
Sanningen är svår för de som drabbas så de föredrar skygglappar och censur.

Om vi håller oss till API, vad är vitsen med ett API om dess gränssnitt ej är dokumenterat?

Lär bli svårt att kunna dra nyttja utav det(även inom samma organisation) om man hela tiden skall skicka e-post eller använda andra metoder för att få ut information om hur man implementerar det.

Skulle det vara ett API för att kommunicera med något så blir det direkt omöjligt att nyttja API:et för just den kommunikation som API:et är avsett för, eftersom ingen annan än utvecklarna utav API:et vet hur det skall nyttjas korrekt för att få till en korrekt kommunikation .

Vad är vitsen med ett API om man har tillgång till källkoden? Mycket snabbare körningar om man kan prata "direkt korrekt" istället för att gå via en mellanhand.

API:er har sitt användningsområde just bl.a. för att källkod inte alltid är tillgänglig utav olika anledningar.

T.o.m. inom stora organisationer så delar man inte alltid källkod med varandra men flera olika projekt vill kunna dra nytta utav varandra för att skapa ett större mervärde för slutkunden, därav API:er, med dokumentation så att man slipper kontakta folk(eller om källkoden är öppen inom organisationen, så slipper man läsa igenom den) och kan fokusera direkt på det resultat man vill ha ut utav den tilltänkta integrationen.

Om man designar sitt API rätt behöver det inte vara så svårt att förstå, speciellt när det rör sådant som Skolplattformen handlar om. Det är ett mål som vissa av oss försöker ha när vi designar och programmerar, ta t.ex. självdokumenterande kod. Om man har litet branschkunskap som rör ett API är det ofta inte svårt att lista ut hur man ska använda det, och tvärtom så designar man ett API så att det är svårt att använda utan dokumentation så har man gjort litet fel.

Nu verkar du sitta i en mer komplicerad verklighet och rätt lång borta från systemutveckling, men försök föreställa dig det finns andra som har andra förutsättningar och gör saker på annat sätt. Jag skulle gissa på att din roll på något sätt innebär att du sätter stämpeln på att dokumentationen är godkänd, så om du inte kan tänka längre än så är det inte meningsfullt att vi diskuterar det här längre.

Att där finns andra verkligheter där man ignorerar att skapa dokumentation för API:er är väldokumenterat i denna tråd . Att hoppas på att någon "räknar" ut hur dom skall anropa ett främmande gränssnitt på 100% korrekt sätt skapar bara mer jobb eftersom antalet felsökningstimmar som kan komma att behövas blir sannolikt fler.

Jag tillät t.ex. aldrig att API:et sattes i skarp drift förrän jag hade testat igenom det och kört det i en labbmiljö som motsvarade 30000 användare(samma mängd som i kundens verklighet). Utvecklaren fick helt enkelt laga felen innan vi släppte det, och det var säkert 30-40 sådana(stora som små) som han fick åtgärda. Det är aldrig värt att smutsa ner ett globalt företags namn oavsett om projektet med API:et var så litet att vi enbart hade en utvecklare hos oss som utvecklade det. Det är klart först när det är klart och vi höll tidsschemat ifrån vår sida. Att det tog kunden nästan 3 år att testa det visade sig vara att dom helt enkelt inte hade en organisation som brydde sig att prioritera det hela förrän deras gamla befintliga lösning började strula.

Sedan att där fanns folk hos beställaren som var svenskar och kallade sig för utvecklare men visade sig att dom inte kunde läsa dokumentationen tillsammans med exemplen som också var skrivna utav utvecklaren på det svenska språket, på ett API med mindre än 20 stycken publika funktioner, var inte vårt fel utan ett internt problem i beställarens organisation.

Den lanserades i mitten på mars månad förra året och än så länge har jag inte hört att där varit några fel som har med utvecklingen eller dokumentationen att göra.

Låter lite som samma kultur i kundens organisation som den man läser om som tråden handlar om men även den verklighet som Du beskriver, där utvecklingen börjar först när man driftsatt systemet skarpt, vilket låter för mig som helt fel ordning.

Men visst, om det är okej att löneutbetalningar, handelsplatser för värdepapper, lagersaldo, beställningar, logistik, kassor, bensinpumpar, hissar, dörrar, portar, kyla/värme, larmsystem, ljus fungerar lite som dom själv vill så förstår jag varför vissa bryr sig att påbörja utvecklingen först efter en skarp driftsättning .

Men å andra sidan så är jag inte förvånad när man ser hur dagens mjukvara ständigt behöver lappas och lagas, och då tänker jag inte på lösningar som finns i fri öppen källkod på nätet, utan i kommersiella lösningar.