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

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

Kuvaus syntyy siitä koodista joka sopimusta valvoo

Jokainen Membershipin päätepiste tarkistaa saapuvan pyynnön skeemaa vasten. Skeema on se asia 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 käynnissä olevasta palvelimesta.

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

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

Dokumentaatio on julkinen, ennen kuin ostat mitään

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

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

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 siihen yhteen yhdistykseen. Kehittäjä ei siis koskaan saa pääsyä siksi että pyysi, vaan siksi että yhdistys valitsi.

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ä: jos avain vuotaa, se on yhden yhdistyksen avain, se näkyy lokissa ja se katkeaa yhdellä klikkauksella.

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 ovat rekisterissä.

Tämä ei ole puuttuva ominaisuus vaan kanta. Kilpailujärjestelmä joka hinnoittelee ilmoittautumisen tarvitsee tietää onko ihminen jäsen. Se 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 napin takana, ja jokainen katselu kirjataan lokiin. Rajapinnan niukkuus on saman periaatteen 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 on muutama kutsu eikä satoja.

Virheet ovat samassa kuoressa 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

Tämän kannattaa olla listassa, koska integraation suunnittelija häviää eniten aikaa oletukseen joka osoittautuu vääräksi. Tällä hetkellä:

• Rajapinta on lukeva. Jäsenen luonti tai päivitys ulkoisesta järjestelmästä ei ole vielä mahdollista.
• Webhookeja ei ole. Muutoksista ei siis tule ilmoitusta, vaan tieto haetaan kysymällä.
• Hiekkalaatikkoa ei ole. Kehitystä varten tarvitaan oikea yhdistys ja oikea parituskoodi.
• Vastausten rakenteita ei vielä kuvata OpenAPI-dokumentissa. Pyyntöjen rakenteet kuvataan, koska niille on skeema; vastauksille ei vielä ole, emmekä halua kirjoittaa niitä käsin, koska juuri sitä tapaa tämä kaikki yrittää välttää.

Nämä ovat työjärjestyksessä, ja kirjoitusten järjestys on harkittu: oikeuksien rajaus pitää ratkaista ennen ensimmäistä kirjoittavaa päätepistettä, koska sen jälkeen jokainen jo myönnetty avain olisi hiljaisesti kaikkivoipa.

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

Jäsenrekisteri on harvoin yhdistyksen ainoa järjestelmä. Mitä helpompi siihen on liittyä, sitä vähemmän kukaan kopioi jäsentietoja käsin taulukkoon, ja käsin kopioitu jäsenrekisteri on se joka lopulta vanhenee ja vuotaa.

Jos rakennat jotain Membershipin päälle ja jokin puuttuu tai on hankalaa, kerro siitä. Toiveet vaikuttavat järjestykseen enemmän kuin arvaat, ja rajapinnan puutteet ovat tässä vaiheessa kirjoitettuja päätöksiä eivätkä kiveen hakattuja.

Julkaistu 15.9.2026. Kaikki artikkelit · Read in English