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

Jokainen aikuinen tunnistaa silmänräpäyksessä olutpullon sen muodon ja värin perusteella. Niin nopeasti myös kokenut kehittäjä havaitsee onko API dokumentaatiosi mistään kotoisin. Onko se tarpeeksi tekninen? Onko se edes API dokumentaatio tai jokin myyntisivu? Silmänräpäys ja sivu on jo vaihtunut.

Tämä ajatteluprosessi ja välitön tunnistaminen ovat osa kehittäjäkokemusta, joka on usein (väärin) käytetty termi. Yksi API tai SDK (ohjelmistokehityspaketti) voi luoda hyvän tai huonon kehittäjäkokemuksen. Puhuttaessa uusien API-hyödyntäjien asiakaspolusta, meidän on puhuttava näiden kehittäjien asiakas- ja käyttökokemuksesta. Tämä sisältyy usein termiin kehittäjäkokemus APIen osalta.

• Millaisia odotuksia kehittäjillä on ohjelmointirajapintojen toiminnasta?
• Miten he saavat pääsyn APIin?
• Pitäisikö heidän maksaa APIsta tai saada se ilmaiseksi, ainakin kokeilemista varten?
• Millaisia esimerkkejä, dokumentaatiota, asettelua ja sisältöä he odottavat ja mistä kanavista he odottavat löytävänsä API?

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 rajapinnoistasi (APIt) tai ohjelmistokehityspaketistasi (SDK).

‍

Ostoa tai käyttöönottoa edeltävät kosketuspisteet ovat paikkoja, joissa kehittäjä ymmärtää, että hänellä on erityinen tarve. Tämä voi olla jotain toiminnallista, kuten kasvojentunnistus tai toimituskulujen laskeminen. Kyse voi olla myös tietojen käyttämisestä, kuten katuosoitteiden kartoittamisesta postinumeroilla. Sitten kehittäjä alkaa etsiä sisäisiä tai ulkoisia ratkaisuja.

Muista, että hänellä on aina mahdollisuus toteuttaa tarvittava ominaisuus itse. Kuten missä tahansa asiakaspolussa, on tärkeää ymmärrettäää kehittäjäasiakkaan aiemman kokemuksen vaikutus. Tämä voi sisältää kokemusta muiden ohjelmointirajapintojen tai muiden palveluiden käytöstä. Nämä aiemmat kokemukset vaikuttavat siihen, miten he näkevät APIsi.

Kun kehittäjä etenee matkalla, hän tarvitsee tavan kokeilla APIa. APIen, kuten minkä tahansa ohjelmistotuotteen, kanssa on tärkeää kokeilla niitä ennen hankintaa. Pidä kyselylomakkeet ja yhteydenotot minimissä, ennen kuin he voivat kokeilla vähintään APIn perusominaisuuksia.

Oston jälkeiset kosketuspisteet ovat kriittisiä, kuten tuen saaminen ja APIn erinomaisuuden markkinointi muille kehittäjille. Kiinniä huomiota kanaviin ja tapoihin, joilla kehittäjät voivat saada apua APIn käyttöön. Riippumatta siitä, mitä päätät tarjota heille tukikanavina, he saattavat etsiä tukea muualta. Kehittäjä saattaa etsiä verkosta tai kuunnella suosikki YouTubereitaan. Hän voi hankkia apua Stackoverflow'n, Gitterin, Redditin tai Discordin kehittäjäyhteisöiltä.

Jos kaikki päättyy hyvin ja kehittäjä ratkaisee koodausongelmansa käyttämällä APIa, he voivat olla parhaita puolestapuhujiasi. He voivat jopa tehdä opetusohjelmia, videoita, hyödyllisiä koodikirjastoja tai käyttää APIa kouluttaakseen muita. He saattavat vastata muiden kehittäjien kysymyksiin APIsta yleisillä tukifoorumeilla ja vähentää tukikuormitustasi.

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 endpointista. Varmista, että se on kirjoitettu kohdeyleisöllesi. Pahin törmäämäni on "Haku API: Haku API on tarkoitettu hakemiseen". Minkä etsimiseen? 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.

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ä kutsuessasi APIamme..."?

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 törmäävät samoihin ongelmiin tai aiheuttavat sinulle haasteita. Korjaa APIsi tai käytä API-hallintaa (katso seuraava kohta). ‍

4. Ole kiltti, älä kaada meidän APIa

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.

‍

5. Validoi skeemasi - ne kaikki

Jos suunnittelet ja julkaiset ohjelmointirajapintojasi OpenAPIlla, ja sinun pitäisi, varmista, että validoit sekä JSON:n, XML:n että YAML:n, mutta mikä tärkeintä, validoit myös OpenAPI-määritystiedoston itse. Ja esimerkkisi. Kehittäjät eivät voi käyttää mitään työkaluja tai kirjastoja suoraan käyttääkseen APIa, jos se ei validoidu.

Ok, tämä oli vain 5 tärkeintä asiaa. Tyypillisesti käymme läpi jopa 20 kohtaa tarkistaaksemme APIsi ja sen dokumentaation.