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.

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 https://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

Tietojen määrätystä lastauksesta saaminen

Lastauksen luominen

Kuten näet, lastaus luotiin onnistuneesti ja tallennettiin EasyCargo-tilillesi.

Tämän jälkeen voit yksinkertaisesti avata luodun lastauksen sovelluksessa.

Lastauksen poistaminen

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.: https://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ä.