Rajapinta, jota ei tarvitse anella: Membershipin periaatteet kehittäjille

Yhdistyksen jäsenrekisteri ei ole erillinen saari. Kilpailujärjestelmä haluaa tietää, kuka saa jäsenhinnan, varausjärjestelmä taas sen, kuka pääsee ovesta, ja kirjanpito tarvitsee laskut. Se, miten helppoa näiden asioiden rakentaminen on, ratkaisee pitkälti sen, kuinka paljon jäsenrekisteristä on todellista hyötyä. Tässä kerromme, miten me ajattelemme asiasta.

Kuvaus syntyy koodista, joka valvoo sopimusta

Jokainen Membershipin päätepiste tarkistaa saapuvan pyynnön skeemaa vasten. Skeema on se tekijä, joka hylkää virheellisen pyynnön, eli se tietää sopimuksen tarkalleen. Siksi rajapintakuvaus muodostetaan samasta skeemasta: osoitteessa /api/v1/openapi.json oleva OpenAPI-kuvaus ei ole käsin kirjoitettu sivu, vaan se luetaan suoraan käynnissä olevasta palvelimesta.

Ero kuulostaa pieneltä, mutta on käytännössä suuri. Käsin ylläpidetty dokumentaatio vanhenee ensimmäisellä kerralla, kun joku lisää kentän ja unohtaa päivittää sivun. Sen jälkeen se on huonompi kuin ei mitään, koska kehittäjä luottaa siihen. Meillä kuvaus ei voi kertoa päätepisteestä, joka ei enää toimi kuvatulla tavalla, koska se lukee suoraan samaa objektia, jota palvelin käyttää.

Kuvaus on koneluettava, joten voit osoittaa asiakasgeneraattorin suoraan siihen ja saada tyypitetyn kirjaston omalle kielellesi ilman, että koodia tarvitsee kirjoittaa käsin.

Dokumentaatio on julkinen jo ennen ostopäätöstä

Rajapintakuvauksen lukeminen ei vaadi avainta, tiliä, tukipyyntöä eikä kalliimpaa tilausta. Tämä on tietoinen valinta. Kehittäjä arvioi järjestelmää usein lauantai-iltana, ennen kuin kukaan soittaa kenellekään. Jos kuvaukseen pääsee käsiksi vasta oston jälkeen, koko arviointi jää usein tekemättä.

Samasta syystä kehittäjädokumentaatio on tavallinen julkinen sivu. Siellä kerrotaan avoimesti myös se, mitä rajapinta ei tee, koska sekin on tietoa, jota integraation suunnittelija tarvitsee jo ennen aloittamista.

Yhdistys päättää, ei kehittäjä

Yhteys syntyy niin, että yhdistyksen ylläpitäjä luo kertakäyttöisen parituskoodin ja antaa sen sinulle. Koodi vaihdetaan API-avaimeen, joka toimii vain kyseiseen yhdistykseen. Kehittäjä ei siis koskaan saa pääsyä vain siksi, että pyysi, vaan siksi, että yhdistys niin päätti.

Avain on peruutettavissa molemmista päistä. Yhdistys näkee liitetyt järjestelmät ja voi katkaista yhteyden koska tahansa, ja integraatio voi katkaista sen itse, kun käyttäjä poistaa sen omasta järjestelmästään. Avaimista tallennetaan vain tiiviste, ja viimeisin käyttöhetki näkyy yhdistykselle. Käytännössä tämä tarkoittaa, että jos avain vuotaa, se koskee vain yhtä yhdistystä, tapahtuma näkyy lokissa ja yhteys voidaan katkaista yhdellä napsautuksella.

Kysymys on jäsenyydestä, ei ihmisestä

Jäsenyyskysely vastaa siihen, onko sähköpostiosoite yhdistyksen hyväksytty jäsen ja mikä jäsenlaji on kyseessä. Se ei palauta puhelinnumeroa, osoitetta, syntymäaikaa eikä lisätietoja, vaikka ne löytyvät rekisteristä.

Tämä ei ole puuttuva ominaisuus, vaan tietoinen valinta. Kilpailujärjestelmä, joka hinnoittelee ilmoittautumisen, tarvitsee tiedon vain siitä, onko henkilö jäsen. Sen ei tarvitse tietää, missä hän asuu. Kun rajapinta antaa vain sen, mitä kysymys vaatii, yhdistyksen ei tarvitse luottaa jokaiseen liitettyyn järjestelmään yhtä paljon kuin itseensä.

Sama ajattelu näkyy muualla tuotteessa. Jäsenen henkilötiedot ovat ylläpitäjältäkin erillisen painikkeen takana, ja jokainen katselukerta kirjataan lokiin. Rajapinnan niukkuus on saman periaatteen luonteva jatke, ei poikkeus siitä.

Rajat kerrotaan etukäteen

Jokaisella päätepisteellä on oma kutsurajansa, ja rajat palautetaan vastauksen otsikoissa standardimuodossa. Eräkysely hyväksyy 200 osoitetta kerralla, koska koko jäsenistön täsmäytys vaatii vain muutaman kutsun satojen sijaan.

Virheet palautetaan samassa muodossa kuin onnistumiset, ja tunnistautumisen epäonnistuminen tarkoittaa yleensä, että yhteys on katkaistu toisesta päästä. Se kannattaa käsitellä päättyneenä yhteytenä eikä virheenä, jota yritetään uudelleen.

Mitä rajapinnasta vielä puuttuu

Nämä asiat kannattaa kertoa suoraan, koska integraation suunnittelija menettää eniten aikaa oletuksiin, jotka osoittautuvat vääriksi. Tällä hetkellä:

• Rajapinta on toistaiseksi vain lukeva. Jäsenen luominen tai päivittäminen ulkoisesta järjestelmästä ei ole vielä mahdollista.
• Webhook-tukea ei vielä ole. Muutoksista ei siis tule automaattista ilmoitusta, vaan tieto haetaan kysymällä.
• Erillistä testiympäristöä (hiekkalaatikkoa) ei ole. Kehitystä varten tarvitaan aito yhdistys ja oikea parituskoodi.
• Vastausten rakenteita ei vielä kuvata OpenAPI-dokumentissa. Pyyntöjen rakenteet kuvataan, koska niille on skeema. Vastauksille skeemaa ei vielä ole, emmekä halua kirjoittaa niitä käsin, koska juuri sellaista käsityötä pyrimme välttämään.

Nämä parannukset ovat työjärjestyksessä, ja toteutusjärjestys on tarkkaan harkittu: oikeuksien rajaus pitää ratkaista ennen ensimmäistä kirjoittavaa päätepistettä, jotta aiemmin myönnetyille avaimille ei synny automaattisesti liian laajoja oikeuksia.

Miksi tämä on meille tärkeää

Jäsenrekisteri on harvoin yhdistyksen ainoa järjestelmä. Mitä helpommin järjestelmät saadaan keskustelemaan keskenään, sitä vähemmän jäsentietoja kopioidaan käsin erillisiin taulukoihin. Käsin kopioitu jäsenrekisteri puolestaan vanhenee ja aiheuttaa tietoturvariskejä.

Jos rakennat jotain Membershipin päälle ja jokin puuttuu tai tuntuu hankalalta, kerro siitä meille. Toiveet vaikuttavat prioriteetteihin enemmän kuin uskotkaan, ja rajapinnan puutteet ovat tässä vaiheessa tietoisia valintoja, eivät kiveen hakattuja totuuksia.

Julkaistu 15.9.2026. Kaikki artikkelit · Read in English