API Overview
Overview of the Pegasus API
Postman
The requests from this documentation can be made via Postman
Resource Patterns
Resources URI patterns try to follow the general convention:
/vehicles
- represents all the vehicles
/vehicles/:id
- represents a particular vehicle ID
/vehicles/:id/remote/state
- see the state of a particular vehicle ID
/vehicles/:id/routes
- see the routes of a particular vehicle ID
etc.
Pagination
Requests to a collection of resources (such as: Users, Vehicles, Devices, etc...) are automatically paginated and will return a set of 200 resources by default.
You can request up to 1000 items per page (up to 500 Devices) by using the set
parameter.
When making request to the resources you will see the following additional fields in the response.
field | description |
---|---|
set | Number of items in current page |
page | Current page |
pages | Total number of pages |
total | Total number of items |
data | Actual data |
Example:
{
"set": 2,
"total": 5,
"data": [...],
"page": 1,
"pages": 3
}
By default the API returns the first page of result (page: 1), to navigate through the total number of pages pass the parameter page
until you reach pages
.
Assume we have 252 vehicles, and we make a request to the API without passing parameters, by default it will return the first 200 items:
GET /vehicles
{
"set": 200,
"total": 252,
"data": [...],
"page": 1,
"pages": 2
}
If we limit the request to sets of 100, then we'll get a response with 3 pages worth of data, (1 & 2 of 100 and the 3rd page with 52)
GET /vehicles?set=100
{
"set": 100,
"total": 252,
"data": [...],
"page": 1,
"pages": 3
}
To navigate through the pages pass page
until you reach pages
GET /vehicles?set=100&page=2
{
"set": 100,
"total": 252,
"data": [...],
"page": 2,
"pages": 3
}
GET /vehicles?set=100&page=3
{
"set": 52,
"total": 252,
"data": [...],
"page": 3,
"pages": 3
}
Since page=pages
we are done traversing the items.
Searching
You can search for specific results on the API using the search
URL param in GET requests.
This param works for all resources except for the /devices
API.
# Search for vehicle names that match
https://api.pegasusgateway.com/vehicles?search.name=CR2013
# Search for trips reports that are generated daily for the past 7 days
https://api.pegasusgateway.com/tasks?search.schedule=[%220%209%20*%20*%20*%22]&search.processes.0.0.script=trips2&search.processes.0.1.back.days=7
HTTP Verbs
verb | meaning |
---|---|
GET | Used for retrieving resources. |
POST | Used for creating resources, sending-info, actions/remote interaction |
PUT | Used for replacing/updating resources. |
DELETE | Used for deleting resources. |
Status codes
code | description | meaning |
---|---|---|
200 | OK | General success status code. |
201 | CREATED | Entity has been created (POST request successful). Response body content may or may not be present. |
204 | NO CONTENT | Status when wrapped responses are not used and nothing is in the body (e.g. DELETE). |
304 | NOT MODIFIED | Used in response to conditional GET calls to reduce bandwidth usage. |
400 | BAD REQUEST | General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. |
401 | UNAUTHORIZED | User is not authenticated with Gateway, does not have permission to upload data, does not have the required scopes, or does not share groups with requested entity |
403 | FORBIDDEN | User is not allowed to perform operation, regardless of scopes or admin level. |
404 | NOT FOUND | Used when the requested resource is not found, whether it doesn't exist or if there was a 401 or 403 that, for security reasons, the service wants to mask. |
409 | CONFLICT | Whenever a resource conflict would be caused by fulfilling the request. Duplicate entries, deleting root objects when cascade-delete not supported are a couple of examples. |
429 | TOO MANY REQUESTS | Too many requests in a given amount of time, both global limits as well as per-resource and per-user limits apply. See rates. |
500 | INTERNAL SERVER ERROR | Catch-all error when the server-side throws an exception. |
Rates
The API handles limits to the different resources on a per user and global rate for the whole site:
- global:
60/minute; 800/hour
- per user:
3/second; 30/minute; 500/hour
- global:
120/minute, 1600/hour
- per user:
6/second, 30/minute, 500/hour
- global:
120/minute, 1600/hour
- per user:
6/second, 30/minute, 500/hour
- global:
2500/minute
- per user:
125/minute
- global:
240/minute
- per user:
80/minute
- global:
1200/minute, 15000/hour
- per user:
200/minute, 4200/hour
Other resources such as vehicles, groups, assets, etc. apply an anti DDOS (Distibuted Denial of Service) limit, which would only be reached if various machines spam the API.
Whenever you hit the limit the API returns a 429 Status Code. At which point it is important that your app suspends more subsequent requests to the API until the limit is reset.
IP Bans
If your app continues to make requests after it hits a 429 the API will eventually block the originating IP address.
// example response when limit is exceeded and an HTTP 429 is returned
{
"reason": "vehicles",
"message": "Rate exceeded",
"limit": 10,
"id": "ec2ec6e51a42f40d12e7009787d833b8",
"value": 11.0455
}
The API returns some response headers which include X-RateLimit-*
keys so you know when it's safe to make requests again.
> HTTP/1.1 429 TOO MANY REQUESTS
> Connection: keep-alive
> Content-Length: 135
> Content-Type: application/json
> Date: Sun, 30 Sep 2018 16:45:13 GMT
> Server: nginx
> X-Peg-Id: 1
> X-Peg-Server: F
> X-Peg-User-Id: 54
> X-RateLimit-Limit: 10
> X-RateLimit-Remaining: 0
> X-RateLimit-Reset: 1538325923
{reason: "vehicles", message: "Rate exceeded", limit: 10, id: "ec2ec6e51a42f40d12e7009787d833b8",…}
The response tells us there's a limit of 10 requests, and the client has 0 remaining, the limit resets back to 10 at the following epoch timestamp: 1538325923 - Sun, 30 Sep 2018 16:45:23 GMT
field | description |
---|---|
reason | resource that reached limit |
message | description |
limit | amount of request allowed |
id | internal use |
value | rate of requests |
header | description |
---|---|
X-Peg-Id | unique ID for pegasus site |
X-Peg-Server | identification of server (internal use) |
X-Peg-User-Id | user id that made the request |
X-RateLimit-Limit | resource limit |
X-RateLimit-Remaining | amount of requests that remain |
X-RateLimit-Reset | when it's safe to make more requests (epoch) |
Solutions for rate limiting
If your application is on the verge or is constantly hitting the api rate limits you can checkout the Live Communications section which allows you to subscribe to the vehicle's data in realtime or Forwarders which allows you to receive all the vehicle's data in a JSON format to any external endpoint, for example your own database for further manipulation.
Units
By default the API uses the following units unless otherwise stated:
Metric | Unit |
---|---|
Distance | meter |
Volume | liter |
Time | second |
Temperature | celsius |
Speed and acceleration units vary per resource, but will normally take the form of
- distance_unit / time_unit
- distance_unit / time_unit /
second
The API's of Rawdata, Counters and Trips support unit parameters, which can modify the output to the desired units.
API Caching
Server level caching is done on requests that are similar, therefore it's important to specify the units of a request in order to make it as atomic as possible. More info below
Allowed values
The API allows you to specify multiple values for each unit of measurement.
Parameter | Allowed values |
---|---|
distance | meter, km, mile |
volume | liter, gallon |
time | second, minute, hour |
temperature | C, F |
You may also pass user
for either the distance
or volume
parameters, where applicable. The API will return the values in accordance with the users preference.
Speed
Where applicable, the speed is determined by the distance and time units (default: meter/second)
The Counters and Trips API's allows you to override this unit, by specifying one of kph , mph or user
, where user
falls back to either kph or mph
based on the users distance preference (mile or km)
Acceleration
The acceleration field is always the speed units, per second
- meter/second/second
- mile/hour/second.
Timezones
The API by default returns all timestamps in UTC (GMT+0).
You can change the timestamp by passing a URL param tz
with an allowed timezone value or an HTTP header value with"X-Time-Zone"
and an allowed timezone value.
URL param: tz=America/New_York
HTTP Header: "X-Time-Zone": "America/New_York"
Caches
Note that the API does server level caching for similar data requests. If for example you make multiple requests for a vehicle's rawdata with a specific date range the first request will hit the server but any subsequent request will hit the cache and return stored data.
To know if a request is cached you can take a look at the response header: x-cache-status
, which will change to HIT
when it's a cached request.
To take advantage of server level caching it's important that the requests are as atomic as possible, meaning that they're specific enough that it will return the exact results you look for. In other words, pass the units and timezone every time so that you get a cache hit.
Updated 4 months ago