"Arkitektura irekia" sektore publikorako softwarearen proposamen komertzial guztietan agertzen den esaldi horietako bat da. Baina praktikan, bezeroak jasotzen duena izugarri alda daiteke: gaizki dokumentatutako endpoint generiko batetik hainbat lengoaiatako SDKak dituen API oso bateraino. Labraxen oso ikuspegi zehatza dugu software bat benetan integragarria izateak zer esan nahi duen, eta artikulu honek ikuspegi hori azaltzen du.
Funtsezko arazoa: sektore publikoaren legacy-a
Tamaina ertaineko administrazio publiko batek 15 eta 40 sistema operatibo artean izan ditzake aldi berean produkzioan: espediente-kudeatzailea, jakinarazpen-plataforma, ordainketa-sistemak, erroldak, egoitza elektronikoa, intranet korporatiboa, giza baliabideen sistemak, herritarren CRMa, arlo zehatzetarako plataforma bertikalak... Software berri bat ekosisteman sartzen denean, garrantzitsua ez da ona den ala ez, baizik eta besteekin batera bizitzeko gai den.
Elkarbizitzak bi dimentsio ditu:
- Datuak jasotzea lehendik dauden sistemetatik (errolda kontsultatzea, nortasuna balidatzea, espedienteak irakurtzea).
- Datuak bidaltzea lehendik dauden sistemetara (jakinarazpenak argitaratzea, egoitzan sarrerak erregistratzea, CRMa elikatzea).
Bi norabideek APIak behar dituzte. Software batek APIrik eskaintzen ez badu, bezeroa uharte batean bizitzera behartzen ari da. Eskaintzen badu baina dokumentatzen ez badu, integragarria dela itxuratzen ari da, benetan ez denean.
Gure estandarra: REST + OpenAPI 3.0
Gure produktu guztiek REST API bat eskaintzen dute, OpenAPI 3.0 zehaztapenarekin. Horrek esan nahi du:
- Egitura aurreikusgarria dela (HTTP aditz estandarrak, egoera-kode zuzenak, JSON erantzunak).
- Dokumentazioa kodea bezala bertsionatuta dagoela, iturburu-kodetik bertatik sortua, dokumentatutakoaren eta errealaren artean aldearik egoteko aukerarik gabe.
- Edozein bezerok tresna estandarrak (Postman, Insomnia, Swagger UI) erabil ditzakeela APIa arakatzeko eta probatzeko.
- SDKak automatikoki sor daitezkeela edozein lengoaiatan, OpenAPI fitxategitik abiatuta.
Autentifikazioa: OAuth2 JWTrekin
Fluxu estandarra OAuth2 Client Credentials da makinaz makinako integrazioetarako, eta Authorization Code PKCErekin giza erabiltzaile bat tartean dagoen fluxuetarako. Tokenak iraungitze laburreko JWTak dira (ordubete), eta refresh tokenak errotazioarekin.
Administrazio publikoentzat ñabardura garrantzitsu bat dago: identitate digital kualifikatua behar duten sistemak (Cl@ve, FNMT, ziurtagiriak) bezeroaren egoitza elektronikoaren bidez konektatzen dira, ez gure API zuzenaren bidez. Gure APIak identitate-kudeatzaile korporatiboari eskuordetzen dio autentifikazioa.
Bertsioak: semver eta atzerako bateragarritasuna
APIaren bertsioa semver esplizituaren bidez adierazten da URLan (/api/v1/recursos). Bateragarritasuna hausten duen aldaketa bat sartzen denean, bertsio nagusia igotzen da (v2), eta v1 martxan mantentzen da gutxienez 24 hilabetez, bezeroek migratzeko denbora izan dezaten.
Aldaketa gehigarriek (eremu berriak, endpoint berriak, errore-kode berriak) ez dute bateragarritasuna hausten eta ez dakarte bertsio-aldaketarik. Horri esker, softwareak bilakatzen jarraitzen du bezeroak etengabe beren integrazioak eguneratzera behartu gabe.
Integrazio-eredu ohikoak
Datuen kontsulta denbora errealean
Eredurik errazena da. Bezeroak GET eskaera bat egiten du, eta guk datuekin erantzuten dugu. Datu txikietarako, noizbehinkako kontsultetarako eta latentzia garrantzitsua den kasuetarako gomendatzen da.
Adibidea: matrikula batek ZBE baimen aktiboa duen egiaztatzea.
Webhookak jakinarazpenetarako
Bezeroak gure sistemako gertaerei erantzun nahi dienean (salaketa berri bat, iraungitako baimen bat), ez du pollingik egin behar. Webhook bat konfiguratzen dugu: gertaera gertatzen denean, gure sistemak HTTP POST eskaera bat egiten dio bezeroaren endpointari, informazio egituratuarekin.
Horretarako, bezeroak endpoint bat izan behar du argitaratuta eta kriptografikoki sinatuta, deia benetan gugandik datorrela balidatzeko.
Inportazio masiboa (bulk operations)
Hasierako kargetarako edo aldizkako sinkronizazioetarako, erregistroz erregistroko APIak ez dira eraginkorrak. Bulk endpointak eskaintzen ditugu: eskaera bakoitzeko 1.000 erregistro arte onartzen dituzte eta eragiketa-identifikatzaile bat itzultzen dute, bezeroak geroago egoera ikusteko kontsulta dezan.
Streaming bidezko gertaerak (Server-Sent Events)
Bezeroak aldaketak denbora errealean ikusi behar dituen kasuetarako (adibidez, salaketak zuzenean erakusten dituen aginte-koadro bat), SSE endpointak eskaintzen ditugu. WebSocketak baino arinagoak dira eta edozein HTTP proxy estandarrekin bateragarriak.
Idenpotentzia: arazorik garestienak saihesten dituen xehetasuna
Sektore publikoko API publikoek arazo berezi bat dute: administrazioen sareek suebaki oldarkorrak, proxy ezegonkorrak eta konexio etenkorrak izan ohi dituzte. POST eragiketa batek huts egin dezake prozesuaren erdian, eta bezeroak ez daki zerbitzarira iritsi den ala ez.
Irtenbidea idenpotentzia da: sortze-eragiketa bakoitzak bezeroak sortutako gako bakar bat darama (Idempotency-Key). Bezeroak eragiketa bera gako berarekin berriro saiatzen badu, zerbitzariak badaki dagoeneko prozesatu zuela eta jatorrizko erantzuna itzultzen du, ekintza bikoiztu gabe.
Horrela, timeout baten ondorioz berriro saiatzen denean ez da "salaketa bikoiztuen" edo "baimen hirukoiztuen" arazorik sortzen.
Dokumentazioa: gehien ahazten den faktorea
Dokumentazio onik gabeko API bat, funtsean, existitzen ez den API bat da. Gure estandarrak honako hauek barne hartzen ditu:
- OpenAPI 3.0 zehaztapen osoa, Swagger UI edo Redoc bidez nabigagarria.
- Eskaera- eta erantzun-adibideak endpoint bakoitzerako, datu adierazgarriekin.
- Hasiera azkarreko tutorialak fluxu ohikoenetarako (autentifikazioa, lehen kontsulta, erroreen kudeaketa).
- Errore-kode dokumentatuak, deskribapenarekin eta gomendatutako ekintzarekin.
- Integrazio-gida espezifikoak sektore publikoan ohikoak diren sistemetarako.
- Postman bildumak, esportagarriak, berehala probatzen hasteko.
- Sandbox publikoa, APIa produkzioan eraginik gabe probatzeko.
Errore egituratuak
Erroreek RFC 7807 formatua jarraitzen dute (Problem Details for HTTP APIs). Mezu librea itzuli beharrean, objektu egituratu bat itzultzen dugu:
{ "type": "https://labrax.es/errors/authorization-not-found", "title": "Ez da baimena aurkitu", "status": 404, "detail": "1234ABC matrikulak ez du baimen indarrekorik.", "instance": "/api/v1/authorizations?plate=1234ABC" }
Horri esker, bezeroek erroreak modu programatikoan kudea ditzakete, hutsegite mota desberdinak bereiziz (autentifikazioa, balidazioa, baliabidea ez da aurkitu, gatazka, barne-errorea) eta egoki erreakzionatuz.
Segurtasun Eskema Nazionalarekiko bateragarritasuna
Gure APIek ENS Altuaren betekizunak betetzen dituzte:
- TLS 1.3 zifratzea derrigorrezkoa (gutxienez TLS 1.2 bateragarritasunerako).
- Eragiketa guztien auditoria-erregistroak, 24 hilabetez gordeak.
- Eragiketa bakoitza egiten duen erabiltzailea edo sistema zalantzarik gabe identifikatzea.
- Edozein baliabideren egoera-aldaketen trazabilitatea.
- Datu pertsonalak geldirik daudenean zifratzea (AES-256).
Bezeroei eskatzen dieguna
Integrazioak bi norabidetan funtzionatzen du. Ondo funtziona dezan, bezeroari ere hau eskatzen diogu:
- HTTP eta JSON ulertzen dituen talde tekniko bat izatea (barnekoa edo kanpokoa).
- Produkziotik bereizitako proba-inguruneak.
- Berriro saiatzeak eta aldi baterako erroreak behar bezala kudeatzea.
- Kredentzialak iturburu-kodean ez gordetzea.
Zure erakundea gure produktuekin integrazio bat ebaluatzen ari bada edo nola planteatu zalantzak badituzu, doako analisi tekniko bat egin dezakegu hedatu aurretik.
