Smartroad RESTful API 2.0
The SmartRoad system provides a RESTful API for developers to interact with external systems.
In general, a request to an external system to obtain an information using unified HTTP methods looks like this:
<url_smartroad>/api/<version>/<request>?login=<user_login>&password=<user_password>
The list of all API requests
| Request | HTTP method | Method description |
|---|---|---|
| login | POST | JWT token obtainment |
| refresh | POST | Token update after expiring |
| events | GET | Receiving events |
| status | GET | Equipment status information |
| stat | GET | Statistics data |
| sensors | GET | Sensor information |
| rate | GET | Traffic flow rating by statistic data showcase |
| jam | GET | Traffic congestion situation rating |
Request parameter list
| Parameter | Description |
|---|---|
| url_smartroad | The address of called web-server. |
| version | The API version. The parameter value depends on API user organization. Default value is 2.0. Any other endpoint (integration or other) can be used as well. |
| request | The called API method. |
| login | A user's login in the System. |
| password | A user's password. |
| username | A user's login used for authorization by the login method. |
| A user's email. | |
| sensorId | A unique identifier of the searched sensor. |
| project_id | A unique identifier of the searched sensor's project. |
| sensorName | A name of the searched sensor. DEPRECATED – an undesirable parameter. |
| startDate / from | The start of time period. |
| endDate / to | The end of time period. |
Request is a mandatory parameter
login and password are also mandatory parameters when JWT token is not used as authorization method
Error Handling
The SmartRoad system uses HTTP status codes to indicate the status of API requests. The HTTP status code is returned in the response header.
A list of status codes which could be received by users:
200: OK400: Bad Request401: Unauthorized403: Forbidden404: Not Found429: Too many requests500: Internal Server Error
Here is the list of all the common errors, which could appear while sending any API requests:
| Error code | Description/message | Obtaining method |
|---|---|---|
| 400 | API not found or disabled | Mistakes/typos in request name occurred, recalling a non-existing request |
| 429 | Too many requests | Less than a certain amount of time has passed between requests. The client application has been throttled and should not attempt to retry the request until a certain amount of time has passed. |
| 500 | Internal server error | An internal server error occurred while processing the request. The server encountered an unexpected internal error or crash. |
Interaction with external systems
The system implements data transfer to external systems through RESTful API in the form of JSON messages at the request of an external system.
External systems interaction schema.
Data is collecting, processing, and sending according to the following algorythm:
- DT collects traffic flow data;
- The adapter generates data packets to send forward to database;
- Web-server receives a data request from an external system;
- Web-server processes the request, with a use of PostgREST requests and receives required data from database;
- Web-server generates and sends a response to the request.
Constraints
Sorb Engineering LLC reserves the right to add new fields without previous notice while maintaining backward compatibility. Please make sure that your software will be able to process the data with fields that may be added in the future without requiring changes in source code.