EasyCargo API -opas (osa 2.)
Kuten jo mainitsimme artikkelin ensimmäisessä osassa, esittelemme nyt EasyCargo API:a käytännön kannalta. Käytämme tähän API-asiakasohjelmaamme. Kokeilemme myös API:n toimintaa online-työkalun ReqBin avulla. Se mahdollistaa kommunikaation verkkopalvelimen kanssa, minkä ansiosta voimme ladata tarvitsemamme tiedot lastauksen EasyCargo-suunnitteluohjelmistostamme.
Testaus on asia sinänsä, mutta todellisessa työssä ehkä käytät ohjelmistoasi varten Java pluginia tai Javascript-toimintoja SAP:sta. Enemmän tästä menetelmästä, Make-alustasta ja muista API:n käytön käytännön esimerkeistä tämän sarjan seuraavassa osassa.
Katso miltä edellä esitetty pyyntö näyttää ReqBin-työkalussa
Ylempänä olevassa kuvassa on API-asiakasohjelmamme EasyCargoa varten. Millaisten tahansa API-pyyntöjen (request) lähettämiseksi verkkopalvelimeen on asiakas ensin valtuutettava. Käynnistyspyyntö on siten POST http://go.easycargo3d.com/api/v1/authentication sekä käyttäjänimi ja API-avain. Vastauksessa saat palvelimesta tunnistevälineen (token). Jokainen seuraava API-pyyntö (ellei ole ilmoitettu toisin) pitäisi todentaa lisäämällä annettu token sen ylätunnisteeseen. Tässä on hyvä huomauttaa, että kaikki API-pyynnöt tapahtuvat tokenin omistajan nimissä. Pyynnöt ja vastaukset on luotava JSON- tai XML-formaatissa.
Todennus on nyt suoritettu ja siirrymme API:n käytön mielenkiintoisempiin puoliin. Oletetaan, että käyttäjä X on tallentanut tililleen seuraavat lastaukset:
Käytämme API-pyyntöjä juuri niissä, sillä lastaukset ovat varmaankin tärkeintä EasyCargossa. Muut pyynnöt kuten esimerkiksi käyttäjähallinta luodaan samalla tavalla, joten oletamme, että luettuasi tämä artikkelin hallitset helposti vastaavat pyynnöt. API-dokumentaatiossa EasyCargoa varten on kuvattu selityksineen kaikki ohjelmointirajapintaa koskevat menetelmät. Älä epäröi kysyä meiltä, jos sinulla on mitä tahansa kysyttävää.
Lastauksia koskevat API-pyynnöt
API-dokumentaatiosta näemme, että oikein luotujen pyyntöjen avulla saamme palvelimesta kaikkien lastausten luettelon ja myös tiedot määrätystä lastauksesta määrätyllä EasyCargo-tilillä. Voimme myös luoda lastauksen tai poistaa sen tililtä.
Kaikkien lastausten luettelon saaminen
Katso miltä edellä esitetty pyyntö näyttää ReqBin-työkalussa
Tietojen määrätystä lastauksesta saaminen
Katso miltä edellä esitetty pyyntö näyttää ReqBin-työkalussa
Lastauksen luominen
Katso miltä edellä esitetty pyyntö näyttää ReqBin-työkalussa
Kuten näet, lastaus luotiin onnistuneesti ja tallennettiin EasyCargo-tilillesi.
Tämän jälkeen voit yksinkertaisesti avata luodun lastauksen sovelluksessa.
Lastauksen poistaminen
Katso miltä edellä esitetty pyyntö näyttää ReqBin-työkalussa
Pyynnön perusteella lastaus poistettiin tililtäsi.
Vielä muutama sana API:sta
- API-pyyntöjen määrä on ajallisesti rajoitettu (60 pyyntöä 1 tunnissa). Määrää valvotaan liikkuvan aikakehyksen puitteissa, joten kyseisellä aikajaksolla on sallittu vain asetettu pyyntöjen määrä.
- API:n virheet lähetetään takaisin tavallisilla HTTP-tilakoodeilla. Useimmissa tapauksissa vastauksen runko sisältää ilmoituksen siitä, mitä tapahtui.
- API:n kautta ei ole mahdollista tehdä lopullisen lastaussuunnitelman laskelmaa. On aina tarpeen, että joku henkilö kirjautuu EasyCargoon ja painaa painiketta Lastaa.
- API-asiakasrajapinnan täytyy tukea pyynnön ja vastauksen ylätunnisteeseen pääsyä ja sen muokkausta ja tietojen analysointia JSON- tai XML-formaatissa.
- Jotta lopullisen lastaussuunnitelman laskelma olisi mahdollista käsitellä, on API:n käyttäjän kirjauduttava EasyCargoon.
- Jotkin API-menetelmät tukevat valinnaisten parametrien, kuten esimerkiksi “from” käyttöä. Kaikkien niiden merkitykset löydät dokumentaatiosta. Näitä parametreja voidaan käyttää esimerkiksi pyydettäessä kaikkien lastausten luetteloa. Lisää parametrit osoitteeseen “?” merkin jälkeen erotettuina merkillä “&” muodossa nimi=arvo, esim.: http://go.easycargo3d.com/api/v1/shipments?from=2020-01-02&offset=0&limit=100.
Kuten varmasti huomasit, API on todella käytännöllinen asia. Tämä artikkeli on toinen osa EasyCargo API -sarjasta ja ellet ole vielä lukenut ensimmäistä osaa, löydät sen täältä. Kolmannessa osassa saat tietää, mitä etuja saat API:mme käytöstä, ja näytämme myös pari esimerkkiä todellisesta elämästä.
