API calls generic description

API calls generic description
 

Every API call is regular HTTP call, what consists of API address, groups and query name and parameters. Let's check following example:

https://app.ecofleet.com/seeme/Api/Reports/getReportConf?id=booking&key=apidemo-NJ8V7PENgkau5FYH 

• https://app.ecofleet.com/seeme/Api/  is API address
• Reports/ is API group. This is like subfolder, what contains subset of commands, or more groups.
• getReportConf is API call under Reports group
• id=booking, key=apidemo-NJ8V7PENgkau5FYH are GET parameters for HTTP call

You have to add always key parameter, what contains value of your API key. All other parameters vary from query to query. Also, you have to escape your parameters correctly to get them working properly.

Second parameter, what you may use for every call, is json. If it exists, system outputs call in JSON format instead of XML.

Response

Default, every API response is in XML format. Here is one example:

<?xml version="1.0" encoding="utf-8" ?>
<nodes>
    <status>0</status>
    <response>
        <node key="0">
            <id>NewDayReport</id>
            <title>Day report</title>
        </node>
    </response>
</nodes>

Status shows, is that query successful or not. All non-zero values indicate for error.

response contains useful content for that query.

Another example:

<?xml version="1.0" encoding="utf-8" ?>
<nodes>
    <status>7</status>
    <response>
    </response>
    <errormessage>No permissions</errormessage>
</nodes>

This example shows, how error message looks like. Status is nonzero (7) and there is element errormessage, what contains details about problem. In our guide, there is troubleshooting section on article of every API call, what describes most error messages, what one may meet.


 

JSON queries

If you add json parameter to your API call, responses are created as JSON values. For example, two last messages in JSON would look like:

Api/Reports/listReports?id=booking&key=apidemo&json

{"status":0,
"response":[{
"id":"booking",
"title":"Booking report"
}]}

And error message:

{"status":7,
"response":null,
"errormessage":"No permissions"}

This manual uses API key apidemo-NJ8V7PENgkau5FYH, what is used in some example calls. Feel free to use it for testing out demo API calls. This API user is isolated from other accounts, so it does not cause any harm to system.

Throttling

API throttling sets, how many queries are available for specified timeframe. API gives error 429 "too many requests", when that limit is exceeded. In every API call, there are three values in query header:

• X-Rate-Limit-Limit: gives limit, how many queries there are available during limit period 

• X-Rate-Limit-Period: shows, in what timeframe query limit is counted 

• X-Rate-Limit-Remaining: shows, how many queries there are left in limit period

Additionally, when 429 is triggered, following header is present: 

• Retry-After: delay in seconds, when next API query comes available

Examples

HTTP error 429

Retry-After: 1
X-RateLimit-Limit: 90
X-RateLimit-Period: 30
X-RateLimit-Remaining: 0

There are no remaining queries (0). Retry-After shows, that successful API query is available after 1 seconds. 

HTTP 200

X-RateLimit-Limit: 90
X-RateLimit-Period: 30
X-RateLimit-Remaining: 45

You can do more 45 queries during 30 seconds.

Overcoming from limits

If you constantly run out of API requests, here are some ideas, how to reduce count of queries. Main idea is that we only count single queries, not amount of data.

• ask last data over all vehicles, not in loop per single objects
• add or update multiple tasks or any other items in one query, if API request allows that

If you still run out of queries, sorry for that, we need to protect our server from overload.