5 asiaa, jotka sinun täytyy kojata API-dokumentaatioosi

7. syyskuuta 2019


Tukholmassa järjestetyn NordicAPI Platform Summit 2018 ensimmäisen päivän juhlissa oli baari, ja hyvä niin! Token-vahvistuksen jälkeen (olutliput olivat tekstiviesteinä), tarvitsin pullon olutta, sillä rehellisesti sanottuna minulla oli jano. Tarvitsin kyseisen pullon osoittaakseni pointtini Ted Epsteinille UX-suunnittelusta API-dokumentaatiota varten. Olin puhunut tästä aiemmin päivällä, mutta nyt pääsimme syvällisemmin kiinni aiheeseen. Ted oli lukenut blogini "Kuinka saada lisää API-käyttäjiä?" ja hänellä oli hienoja kysymyksiä siitä, erityisesti lausuntonnostani "Sivustosi ei saa olla kaunis".

Joten ryntäsin tiskille osoittaen olut-, sooda- ja viinipulloja. Jokainen aikuinen tunnistaa silmänräpäyksessä mikä on mitäkin pullon muodon ja värin perusteella. Niin kauan kokeneella kehittäjällä menee päättää, onko API-dokumentaatio tapeeksi arvokasta lukea. Onko se tarpeeksi tekninen? Onko kyseessä edes API-dokumentaatio tai jokin muu myyntisivu? Silmänräpäytys. Jatka eteenpäin.

Olen hämmentynyt siitä, miten UX-ihmiset ajattelevat, että kehittäjäkokemus ei ole relevantti asia. Enkä ole ainoa. Syvällä sisimmässään he ovat tietenkin oikeassa. Kehittäjäkokemus kuvaa vain tyypillisten kehittäjien tarpeita API-liittymien, SDK:iden tai muiden kehittäjätyökalujen avulla. Tiettyjä segmenttejä tarkastellessa kehittäjäkokemuksessa ei ole kyse vain käyttökokemuksesta, vaan myös asiakaskokemuksesta. Ja ennen kaikkea vaikutukset rajapintojen suunnitteluun ovat erilaiset. Kyseessä ei ole vain verkkosivusto, joka sisältää dokumentaatiota, tai työkalut, joita he käyttävät API-pyyntöjen koodaamiseen tai teemiseen. Kyse on teknisten rajapintojen, esimerkiksi ohjelmointirajapintojen (Application Programming Interfaces) suunnittelusta. Nämä rajapinnat eivät ole (vain) suunniteltu ihmisille, vaan myös ohjelmistojen, tietokoneiden ja verkkolaitteiden optimaaliseen käyttöön.

Olen samaa mieltä, jos monet UX-suunnittelua harjoittavat eivät olisi niin tiukasti sidoksissa käsillä olevan tuotetarjonnan käyttöliittymään. Poista dokumentaatio, portaali, rekisteröintiprosessi ja ne ovat kaikki mennyttä, kun tuotteesta tulee http-lauseita langan yli. Mutta DX pätee edelleen silti.— Matthew Reinbold (@libel_vox) Lokakuu 23, 2018.

Edes kehittäjät eivät ole yksi identtinen ryhmä. Heidän odotuksensa vaihtelevat sen mukaan, keitä he ovat. Junior vs. senior, front-end vs. backend vs. integrointi, ohjelmointikielet ja työkalut, joita he käyttävät. Kehittäjät eivät tietenkään ole ainoa käyttäjäryhmä, jolle sinun tulee puhua API-liittymistäsi tai ohjelmistokehityspaketistasi.

Developers try, business buys - Jason Harmon, Typeform, NordicAPIs Platform Summit 2018

Siirrytään niihin 5 asiaan, jotka sinun on muutettava dokumentaatiossasi:

1. Mitä APIsi tekee?

Tämän tulisi ilmetä API-dokumentaatiosi ensimmäisestä otsikosta ja lauseesta. Ja jokaisesta päätepisteestä. Varmista, että se on kirjoitettu kohdeyleisöllesi. Pahin törmäämäni on "Search API: Search API is used to do searches". Hyvä on, mutta etsimään mitä? Miksi? Onko olemassa rajoituksia tai erityisiä yhdistelmiä? Jos kyseessä on API kehittäjäportaalissa, joka sisältää julkisia, kumppani- ja yksityisiä ohjelmointirajapintoja, kenelle tämä API on? Vai voisiko sen avata kaikille? Tämä sinun tulee huomioida jo APIn suunnitteluvaiheessa.

Wrong purpose, terrible API - Arnaud Lauret, API Handyman, NordicAPIs Platform Summit 2018

Tämä on myös lähtökohta Creative Commons -lisensoidussa APIOps Cycles -menetelmässä API-kehitykselle. Kaikki alkaa API-arvoehdotuksista.

2. Älä tyydy sekvenssikaavioihin, selitä tuotteesi

Luuletko kehittäjien tietävän mitä sinun APIa käyttävä tuotteesi tai palvelusi todella tekee? Tuotteesi tai palvelusi saattaa tarvita spesifiä tietoa. Kuten kirjanpito-ohjelmisto, maksupalvelu tai transkriptiopalvelu. Jos et ymmärrä miten ne toimivat, sinun on voi olla vaikea ymmärtää, mitä API tekee.

Saatat tuntea kiusausta laittaa vuokaavioita tai sekvenssikaavioita API-dokumentaatioosi. Näin tapahtuu yleensä, jos kaavioita on tehty APIa kehittäessä. Kuva kertoo enemmän kuin tuhat sanaa, eikö vain?

Väärin.

Tämänkaltaiset kaaviot on usein piirretty sisäisestä näkökulmasta, ja niistä puuttuu tuotteesi käyttäjävirta. Jos sinulla on 10 erilaista päätepistettä APIllesi, ulkoinen kehittäjä tarvitsee todennäköisesti prosessikaavion. Sen pitäisi näyttää tyypillinen työnkulku tuotteen käyttöön tai tietyn tehtävän suorittamiseen tuotteessa. Bonuksena myös se, mitä päätepisteitä tarvitaan. Selvennä nämä asiat yksinkertaisella 1-5 kohdan luettelolla. Jos tämä ei ole mahdollista, kannattaa ehkä harkita vielä varsinaisen tuotteen yksinkertaistamista.

3. Vähemmän sanoja, parempi API

Ota nyt esiin mittanauha. Kopioi teksti Wordiin tai muuhun alustaan, joka näyttää API-dokumentaatiosi sanamäärän. Jos sinulla on yli 300 sanaa tekstiä, ole hieman huolissasi. Katso tekstiäsi. Näyttääkö se tältä: "Sinun pitäisi käyttää suojattuja yhteyksiä soittaessasi API:llemme..."?

Jos sinun on kirjoitettava kaikki nämä asiat, se on merkki: ehkä uudelleenohjaus on tarpeen.

1) olet palkannut ''ei-API'' -teknisen kirjoittajan tekemään API-dokumentaatiosi, tai

2) API-käyttäjäsi kompastuvat samoihin ongelmiin tai aiheuttavat sinulle lisää ongelmia. Tässä tilanteessa sinun tulee korjata APIsi tai käyttää API-hallintaa. (katso seuraava kohta).

Hyvä herra, ole kiltti ja älä kaada APIani

Lopeta tyhjät pyynnöt kuten: "Älä soita liikaa puheluita APIllemme, ainakaan työaikana". Jos joku voi kaataa APIsi soittamalla milloin haluaa, se tulee tapahtumaan. Eikä siksi, etteivätkö he olisi ystävällisiä. Vaan siksi, koska joku voi tehdä koodausvirheen ja roskapostata APIisi vahingossa. Kerran iäkäs nainen laittoi kahvimukinsa näppäimistön päälle, ja onnistui kaatamaan kokonaisen SaaS-sovelluksen soittamalla liikaa puheluita. Pahat ihmiset voivat yrittävää kaataa APIsi. Sanot, että sinulla ei ole mitään, mikä estäisi heitä, ainakaan hidastamasta hakemustasi.

Yksi kriittinen neuvo: aseta vähintään kova enimmäishintaraja APIllesi (per minuutti ja käyttäjä) ja älykäs geneerinen virheviesti.

Tässä oli vain viisi tärkeintä asiaa. Tyypillisesti käymme läpi jopa 20 asiaa  tarkistaessamme APIsi ja dokumentaatiosi.

Takaisin blogiin

viimeisimmät blogimme

Uutisia, asiakastarinoita, parhaita käytäntöjä ja paljon muuta - katso, mitä me ja asiakkaamme ja kumppanimme olemme tehneet viime aikoina

Miksi APIt kannattaa tuotteistaa?
Mitä hyötyä APIen tuotteistamisesta on? Lue lisää täältä!
16. kesäkuuta 2021
Millainen on hyvä API-tuotepäällikkö?
Kaksi API-gurua, Marjukka Niinioja ja Claire Barrett keskustelevat API-tuotepäällikön roolista ja odotuksista ja jakavat itetämystään menestyksekkäästä API-tuotehallinnasta.
14. kesäkuuta 2021
Osaango & KAVI – innovatiivisia, älykkäitä hankintoja
Kansallinen audiovisuaalinen instituutti KAVI tallentaa vuosittain valtavat määrät dataa, ja vastaa muun muassa kotimaisten elokuvien sekä televisio- ja radio-ohjelmien säilyttämisestä. Kriittisen tärkeässä osassa KAVIn toiminnassa on tekoäly. Osaangon Marjukka Niinioja ja Tessa Viitanen sparrasivat KAVIa heidän mittavassa toiminnan ja tekniikan muutos-casessa tekoälyyn pohjautuvien ratkaisujen, innovatiivisten hankintamenettelyjen, ohjelmistokehitysprosesssien ja arkkitehtuurin osalta.
27. toukokuuta 2021