API Overview

Overview of the Pegasus API

Postman

The requests from this documentation can be made via Postman

Run in 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.

fielddescription
setNumber of items in current page
pageCurrent page
pagesTotal number of pages
totalTotal number of items
dataActual data

Example:

/vehicles

{
  "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

verbmeaning
GETUsed for retrieving resources.
POSTUsed for creating resources, sending-info, actions/remote interaction
PUTUsed for replacing/updating resources.
DELETEUsed for deleting resources.

Status codes

codedescriptionmeaning
200OKGeneral success status code.
201CREATEDEntity has been created (POST request successful). Response body content may or may not be present.
204NO CONTENTStatus when wrapped responses are not used and nothing is in the body (e.g. DELETE).
304NOT MODIFIEDUsed in response to conditional GET calls to reduce bandwidth usage.
400BAD REQUESTGeneral error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc.
401UNAUTHORIZEDUser 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
403FORBIDDENUser is not allowed to perform operation, regardless of scopes or admin level.
404NOT FOUNDUsed 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.
409CONFLICTWhenever 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.
429TOO MANY REQUESTSToo many requests in a given amount of time, both global limits as well as per-resource and per-user limits apply. See rates.
500INTERNAL SERVER ERRORCatch-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:

Rawdata & Counters:

  • global: 60/minute; 800/hour
  • per user: 3/second; 30/minute; 500/hour

Trips:

  • global: 120/minute, 1600/hour
  • per user: 6/second, 30/minute, 500/hour

Geofences:

  • global: 2500/minute
  • per user: 125/minute

Geofence Types

  • global: 240/minute
  • per user: 80/minute

Reversegeo

  • global: 1200/minute, 15000/hour
  • per user: 200/minute, 4200/hour

Apps Resources

  • global: 20/second
  • per user: 5/second, 20/minute

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

fielddescription
reasonresource that reached limit
messagedescription
limitamount of request allowed
idinternal use
valuerate of requests
headerdescription
X-Peg-Idunique ID for pegasus site
X-Peg-Serveridentification of server (internal use)
X-Peg-User-Iduser id that made the request
X-RateLimit-Limitresource limit
X-RateLimit-Remainingamount of requests that remain
X-RateLimit-Resetwhen 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:

MetricUnit
Distancemeter
Volumeliter
Timesecond
Temperaturecelsius

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.

ParameterAllowed values
distancemeter, km, mile
volumeliter, gallon
timesecond, minute, hour
temperatureC, 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.


What’s Next