Sisällysluettelo:
- Tee kotitehtäväsi
- Ole johdonmukainen
- Käytä OAuthia
- Aloita varhain
- Kirjoita hyvä dokumentaatio
- Sovellusliittymäkehitys: Pidä se yksinkertaisena
Se on ohjelmistokehityksen luonne. Kehittäjät luovat ohjelmistoja loppukäyttäjän mielessä. Vaikuttaa melko yksinkertaiselta, mutta joskus nämä käyttäjät ovat myös kehittäjiä. He eivät tarvitse heille hajotettuja asioita. He eivät tarvitse edes yksinkertaisuutta. He haluavat vain pääsyn - tapa integroida ohjelmistosi omaan. Tässä tulee sovellusliittymä (sovellusohjelmointirajapinta). Toivon korostavan viisi vaihetta, jotka voit suorittaa onnistuneen sovellusliittymän luomiseksi.
Tee kotitehtäväsi
Ohjelmistokehityksen yhteydessä kukaan meistä ei halua keksiä pyörää uudelleen. Tässä vaiheessa melkein kaikilla suurilla verkkoyrityksillä on sovellusliittymät ohjelmistotuotteilleen. Tutki näitä sovellusliittymiä ja yritä poimia erilaisia suunnittelupäätöksiä, jotka ovat johtaneet niiden luomiseen.
Siellä on monia erilaisia tekniikoita, mutta suurin osa näkemistäsi sovellusliittymistä käyttää joko RESTful-käyttöliittymää tai SOAP-tekniikkaa. Jos olet aidalla, mitä sovellusliittymää käytät, ehdotan RESTful-lähestymistapaa HTTP-protokollan avulla. Se on yksinkertaisempi kuin SOAP, se on nykyään suositumpi, ja siitä on helpompi aloittaa, kun käytät Web-pohjaista ohjelmistotuotetta.
Ole johdonmukainen
Yksi asioista, joita kehittäjät arvostavat eniten, on johdonmukaisuus. Tähän sisältyy muun muassa osoitettavuus, syöttöargumentit, lähtömuodot ja virheiden käsittely.
Kun käytetään RESTful-lähestymistapaa, on olemassa monia erilaisia URI-nimeämismalleja. Jokaisella niistä on kannattajia, joten valitse vain yksi ja pysy siinä. Sama pätee tulo- ja lähtörakenteeseen. Useimmat sovellusliittymät tukevat XML: n ja JSON: n käyttöä tulo- ja lähtömuotoina. Ehdotan tukevan molempia, mutta valitsemalla oletusmuodon.
Syöttöä varten syöttötarpeesi olisi nimettävä johdonmukaisesti, ja niiden olisi oltava järkeviä tekemäsi API-puhelun yhteydessä. Tulostusta varten varmista, että käytät yleisiä tietorakenteiden asetteluja. Jos käärimässä yhden API-puhelun lähtö on
Yleinen käytäntö on sisällyttää jonkinlainen tilamerkki lipputietoihin, jotka lähetät takaisin asiakkaalle. Kun käytetään RESTful API -lähestymistapaa, tämä tulisi tehdä HTTP-tilakoodien avulla. Jos esimerkiksi käsittelisit juuri PUT-pyyntöä olemassa olevassa dataobjektissa, vastaukseesi lisäämä HTTP-tilakoodi vaihtelee pyynnön lopputuloksen mukaan.
Puhelun tilaa osoittavan mielivaltaisen lipun sijasta voidaan käyttää vakiona olevaa "200 OK" -koodia osoittaakseen, että pyyntö on onnistunut, kun taas "400 huonoa pyyntöä" -koodia voidaan käyttää osoittamaan, että pyyntö oli virheellinen. HTTP-tilakoodeja, joita voidaan käyttää eri tilanteissa, on melko vähän.
Käytä OAuthia
Useimpiin ohjelmistotuotteisiin sisältyy jonkinlainen käyttäjän todennus käyttäjän suojattujen resurssien käyttämiseksi. Sovellusliittymien osalta on huono käytäntö, jos asiakas kerää käyttäjän käyttäjätiedot palvelimellesi lähettämistä varten. Tässä OAuth tulee sisään.
OAuth tarjoaa monia etuja verrattuna kolmannen osapuolen käyttäjätunnuksen ja salasanan todennukseen. Ennen kaikkea asiakkaalla ei ole koskaan pääsyä käyttäjän valtuustietoihin. Käyttäjä ohjataan palvelimellesi, kun hän kirjautuu sisään. Kun käyttäjä on kirjautunut sisään sivustoosi, hänet ohjataan takaisin asiakkaalle, jossa asiakas saa käyttöoikeustunnuksen käytettäväksi tulevaisuudessa suojattuja resursseja koskevissa pyynnöissä.
Toinen tärkeä hyöty OAuthin käytöstä on käyttäjän kyky peruuttaa asiakasoikeudet milloin tahansa. Jos käyttäjä päättää, että jostain syystä he eivät enää halua, että asiakas voi käyttää suojattuja resursseja hänen puolestaan, hän menee yksinkertaisesti luomallesi käyttöliittymälle ja peruuttaa asiakkaan pääsyn.
Aloita varhain
Yksi tärkeimmistä asioista, joita voit tehdä API: n menestymiseksi, on aloittaa aikaisin. Kun kirjoitat tämän toiminnon luodaksesi jonkin merkinnän tietokantaan, mene eteenpäin ja vie ylimääräinen aika ja kirjoita siihen sovellusliittymä.Kirjoita hyvä dokumentaatio
Mikään ei tapa API: ta nopeammin kuin sillä, että sillä ei ole hyvää dokumentaatiota. Jotkut kehittäjät voivat ottaa huonosti dokumentoidun sovellusliittymän ja selvittää, kuinka sen pitäisi toimia, mutta useimmat eivät halua.
Sinun tulisi dokumentoida jokainen käytettävissäsi oleva API-puhelu ja luokitella API-puhelut sen mukaan, minkä tyyppisiä tietoja he käyttävät. API-kutsujen itse päätepisteiden dokumentoinnin lisäksi sinun tulisi määritellä systemaattisesti vaadittavat ja valinnaiset syöttöargumentit sekä lähtödatan rakenteet. Syöttöargumenteissa tulee olla luettelo oletusarvosta, jos sellainen on, ja ilmoittaa myös odotettu tietomuoto, kuten numero tai merkkijono. Viimeisenä, jokaisella API-puhelulla tulisi olla luettelo virheolosuhteista ja tilakoodeista.
Voit pyöristää asiakirjat sisällyttämällä jokaiseen API-puheluun yhden tai kaksi esimerkkiä yleisistä syöttö- ja tulostusskenaarioista.
Sovellusliittymäkehitys: Pidä se yksinkertaisena
Vaikka saattaa vaikuttaa siltä, että sovellusliittymän kehittäminen on monimutkainen yritys, itse sovellusliittymän idea ei ole uusi käsite, ja jokaisesta täällä käsitellystä aiheesta on saatavana suuri määrä dokumentaatiota. Varmista vain, että käytät hyviä käytäntöjä mistä löydät ne, ja tarjoa johdonmukainen, dokumentoitu käyttöliittymä.
