API in EasyCargo (part 2)
In today’s article, we will approach the EasyCargo API more from the practical side. We will use our API client for this. We will also test the operation of the API using the ReqBin online tool. It enables communication with a WWW server, thanks to which we can download data of interest from our EasyCargo container loading calculator. Testing is one thing, but in real life, you might be using a Java plugin for your software or Javascript calls from SAP. More on this and other real-world API use cases in the next post in this series.
The image above shows the API client for EasyCargo. To be able to send any API requests to the web server, the client must first be authorized. So the start request is a POST http://go.easycargo3d.com/api/v1/authentication with the user’s username and his API key in the content. You will receive an authentication token from the server in the response. Each subsequent (unless otherwise noted) API request should be authenticated by adding the obtained token in its header. It is worth noting here that all API requests made are made on behalf of the token owner. Requests and responses must be created in JSON or XML format.
Now that we’ve been authenticated, let’s finally get to the more interesting part of the API. Let’s assume that user A has the following shipping loads stored in his account:
We will practice API requests on them because shipping loads are probably the most important part of EasyCargo. Other requests such as user management are formulated in a similar way, so we believe that every reader of this article will be able to handle the creation of other requests. In the API documentation for EasyCargo, every method of the programming interface is described and explained.
API shipments requests
As the API documentation informs us, with properly worded requests we are able to get a list of all shipments from the server, as well as data about a specific load from the EasyCargo account. We can even create or delete a shipment from the account.
Getting list of all shipments
Getting data about a specific load
Creating a shipment
As you can see, the load was successfully saved to your EasyCargo account.
You can simply open the loading created by the API method in your application.
Deleting a shipment
The shipping load was correctly removed from your EasyCargo account with the appropriate request.
A few more words about EasyCargo API
- The number of your API requests is limited in time (60 requests per 1 hour). The quotas are checked by moving time frame, so at any given time period is allowed only the specified number of requests.
- API errors are sent back by common HTTP status codes. In most cases, the response body contains a specific message about what went wrong.
- The load planning calculation cannot be executed through the API.
- Your API client has to support accessing and modifying the request and response header and parsing either JSON or XML data format.
- The API user has to sign into the EasyCargo application so that the calculation of the load plan can be processed.
- Some API methods support the use of optional parameters, such as from. You will naturally learn the meaning of each of them from the documentation. You can use these parameters, for example, when requesting to get a list of all payloads. Just add them to the resource address after the “?” character, separated by the “&” character in the form name=value, e.g. http://go.easycargo3d.com/api/v1/shipments?from=2020-01-02&offset=0&limit=100.
As you can see, API is a very useful service. We hope that this practical description has explained to you more about how a programming interface works. Today’s article is the second in a series about the API for EasyCargo, so if you haven’t seen the first part yet, you can read it here. The programming interface opens a floodgate of possibilities. In the next post, you will find out what benefits you can have from using our API and learn about its real-life use cases.
