API on juuri niin hyvä kuin sen dokumentaatio, joten varmista, että omasi on löydettävissä huippulaadukkaiden ohjeiden ja muiden tärkeiden yksityiskohtien avulla.

Yhä useammat organisaatiot hyödyntävät sovellusliittymien tehoa liiketoimintansa optimoinnissa. API-liittymistä on tullut tapa avata arvoa ja tarjota lisäpalvelua.

Yleisestä suosiosta huolimatta kaikki API eivät ole menestys. API: n käyttöönotto ja käyttö määräävät suurelta osin sen menestyksen. Käyttöönoton lisäämiseksi sovellusliittymäsi on oltava helppo löytää ja käyttää.

Paras tapa tehdä tämä on dokumentoida API yksityiskohtaisesti. Tämä sisältää kriittisten osien yksityiskohdat, jotta ne on helpompi ymmärtää. Ota selvää komponenteista, jotka sinun tulee sisällyttää API-dokumentaatioosi.

Mikä on API-dokumentaatio?

API-dokumentaatio on teknistä sisältöä, jossa kuvataan API yksityiskohtaisesti. Se on käsikirja, joka sisältää kaikki API: n kanssa työskentelyyn tarvittavat tiedot. Dokumentti kattaa API-elinkaarin ja ohjeet sen komponenttien integroimiseen ja käyttöön.

instagram viewer

API-dokumentaatio kattaa resurssien kuvaukset, päätepisteet, menetelmät, pyynnöt ja vastausesimerkit. Se voi myös sisältää käytännön oppaita ja opetusohjelmia, joissa näytetään käyttäjille, kuinka se integroidaan. Kunkin osion tutkiminen antaa käyttäjille vankan käsityksen API: n integroinnista ja käytöstä.

Editoreita, kuten Google-dokumentteja, käytettiin aikoinaan laajalti ammattimaiseen API-dokumentaatioon. Nykyään on olemassa kehittyneempiä työkaluja, kuten Document 360, Confluence ja GitHub Pages. Nämä työkalut auttavat integroimaan tekstiä ja koodia työnkulkujen helpottamiseksi.

1. API: n yleiskatsaus ja tarkoitus

Ensimmäinen askel API: n dokumentoinnissa on kertoa käyttäjille, mistä on kyse. Sisällytä tiedot sen tarjoamista resurssien tyypeistä. Sovellusliittymillä on yleensä erilaisia ​​resursseja, jotka ne palauttavat, joten käyttäjä voi pyytää tarvitsemaansa.

Kuvaus on lyhyt, yleensä yhdestä kolmeen lausetta, jotka kuvaavat resurssia. Kuvaa käytettävissä oleva resurssi, päätepisteet ja kuhunkin päätepisteeseen liitetyt menetelmät. API-kehittäjänä kuvailet parhaiten sen komponentteja, toimintoja ja käyttötapauksia.

Tässä on esimerkki Airbnb-sovellusliittymän kuvauksesta:

2. Todennus- ja valtuutusmenetelmät

API: t käsittelevät tuhansia pyyntöjä ja valtavia tietomääriä. Todennus on yksi tavoista varmistaa, että API- ja käyttäjätietosi ovat turvassa hakkereilta. API-todennus vahvistaa käyttäjän henkilöllisyyden ja antaa heille pääsyn resursseihin.

On olemassa useita tapoja varmistaa päätepisteen suojaus. Useimmat sovellusliittymät käyttävät API-avainta. Tämä on merkkijono, jonka käyttäjä voi luoda verkkosivustolta ja käyttää todentamiseen.

API-dokumentaation tulisi opastaa käyttäjiä henkilöllisyytensä todentamisessa ja valtuutuksessa. Seuraava kaavio näyttää Twitter API -todennustiedot.

3. Päätepisteet, URI-mallit ja HTTP-menetelmät

Tässä osiossa osoita, kuinka resurssia käytetään. Päätepisteet näyttävät vain polun lopun, joten niiden nimi. Ne osoittavat pääsyn resurssiin ja HTTP-menetelmiä päätepiste on vuorovaikutuksessa, nimittäin GET, POST tai DELETE.

Yhdellä resurssilla on todennäköisesti useita päätepisteitä. Jokaisella on erilainen polku ja menetelmä. Päätepisteillä on yleensä lyhyt kuvaus niiden tarkoituksesta ja URL-malli.

Seuraava koodiesimerkki näyttää GET-käyttäjän päätepisteen Instagramissa.

SAAT /minä? fields={fields}&access_token={access-token}

4. Pyyntö- ja vastausmuodot

Sinun on dokumentoitava pyyntö- ja vastausmuodot, jotta käyttäjä tietää, mitä odottaa. Pyyntö on URL-osoite asiakkaalta, joka pyytää resurssia, kun taas vastaus on palaute palvelimelta.

Seuraava on esimerkkipyyntö, jonka voit lähettää LinkedIn API: lle.

SAADA https://api.linkedin.com/v2/{service}/1234

Ja tässä on esimerkkivastaus, jonka se voi palauttaa:

{
 "id": 1234,
 "relatedEntity": "urn: li: relatedEntity: 6789"
}

5. Parametrit ja otsikot

Sinun tulee myös dokumentoida päätepisteidesi parametrit, jotka ovat vaihtoehtoja, jotka voit välittää niille. Parametrit voivat olla tunnus tai numero, joka määrittää vastauksena palautettujen tietojen määrän tai tyypin.

Parametreja on erilaisia, mukaan lukien otsikko-, polku- ja kyselymerkkijonoparametrit. Päätepisteet voivat sisältää erityyppisiä parametreja.

Voit sisällyttää joitain parametreja HTTP-pyyntöotsikoiksi. Yleensä nämä ovat todennustarkoituksiin, kuten API-avain. Tässä on esimerkki ylätunnisteesta, jossa on API-avaimia:

otsikot: {
 "X-RapidAPI-Key": "fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635",
 "X-RapidAPI-Host": "wft-geo-db.p.rapidapi.com"
}

Lisäät polkuparametrit päätepisteen tekstiin suoraan URL-osoitteessa. Ne näyttävät käyttäjälle, kuinka ja minne parametrit sijoitetaan ja miten vastaus tulee näkyviin. Aaltosulkeissa olevat sanat ovat parametreja.

Voit myös käyttää kaksoispisteitä tai muuta syntaksia polkuparametrien esittämiseen.

/service/myresource/user/{user}/bicycles/{bicycleId}

Kyselyparametreja käytettäessä sinun on sijoitettava kysymysmerkki (?) ennen kyselyä päätepisteessä. Erottele jokainen parametri sen jälkeen et-merkillä (&). Microsoftilla on hyvä dokumentaatio Graph API: sta.

6. Virhekoodit ja virheiden käsittely

Joskus HTTP-pyynnöt epäonnistuvat, mikä voi hämmentää käyttäjää. Sisällytä dokumentaatioon odotetut virhekoodit, jotta käyttäjät ymmärtävät virheet.

LinkedIn tarjoaa standardinmukaisia ​​HTTP-virhekoodeja virheiden käsittelyyn:

7. Esimerkkikoodinpätkät

Koodinpätkät ovat olennainen osa dokumentaatiota. Ne osoittavat käyttäjille kuinka integroida API eri kielillä ja muodoissa. Sisällytä dokumentaatioon, kuinka SDK: ita (ohjelmistokehityspaketteja) asennetaan ja integroidaan eri kielillä.

RapidAPI: lla on hyviä esimerkkejä koodinpätkistä kehittäjille:

9. API-version ja muutoslokit

API-versiointi on olennainen osa API-suunnittelu. Se varmistaa keskeytymättömät palvelut käyttäjillesi. Versiointi voi parantaa API: ta uusilla versioilla vaikuttamatta asiakassovelluksiin.

Käyttäjät voivat jatkaa vanhempien versioiden käyttöä tai siirtyä edistyneisiin versioihin ajoissa. Jos lokeihin tulee uusia muutoksia, sisällytä ne dokumentaatioon, jotta käyttäjät tietävät.

Microsoft Graph API sisältää hyvin dokumentoidut muutoslokit:

Lisää lopuksi tärkeät yhteystiedot dokumentaatioon tukea ja palautetta varten. Nämä varmistavat, että käyttäjät voivat saada sinuun virheraportteja ja tietoja API: n parantamisesta.

API-dokumentaation arvo

Jos rakennat API: n kaupallista arvoa varten, kulutus määrää sen menestyksen. Ja jotta käyttäjät voivat käyttää sovellusliittymääsi, heidän on ymmärrettävä se.

Dokumentaatio herättää sovellusliittymän henkiin. Se selittää komponentit yksityiskohtaisesti yksinkertaisella kielellä, joka myy arvonsa ja käyttötarkoituksensa käyttäjille. Käyttäjät käyttävät sovellusliittymääsi mielellään, jos heillä on loistava kehittäjäkokemus.

Hyvä dokumentaatio auttaa myös yksinkertaistamaan API: n ylläpitoa ja skaalausta. API: n kanssa työskentelevät tiimit voivat hallita sitä dokumentaation avulla.