This is the Trips API for the Trip Insights service.
The Trips API has a dependency on a SQL Server compatible database to store the trips and trip points.
| Method | Path | Description |
|---|---|---|
| GET | /api/trips | List all the trips |
| GET | /api/trips/{tripID} | Fetch an existing trip |
| POST | /api/trips | Create a new trip |
| PATCH | /api/trips/{tripID} | Update an existing trip |
| DELETE | /api/trips/{tripID} | Delete an existing trip |
| GET | /api/trips/user/{userID} | List all the trips for the specified user |
| GET | /api/trips/{tripID}/trippoints | List all the trip points for an existing trip |
| GET | /api/trips/{tripID}/trippoints/{tripPointID} | Fetch an existing trip point for an existing trip |
| POST | /api/trips/{tripID}/trippoints | Create a new trip point for an existing trip |
| PATCH | /api/trips/{tripID}/trippoints/{tripPointID} | Update an existing trip point for an existing trip |
| DELETE | /api/trips/{tripID}/trippoints/{tripPointID} | Delete an existing trip point for an existing trip |
| GET | /api/trips/healthcheck | Return the healthcheck status for the Trips API |
| GET | /api/docs/trips | Return the OpenAPI documentation for the Trips API |
The following paths must be allowed by any network appliance or gateway that is controlling inbound access to this API. These are all paths the OpenAPI controller will leverage to build its resources.
| Method | Path | Description |
|---|---|---|
| GET | /api/json | Required by the OpenAPI controller |
The api has been instrumented using the Go Promethues library.
| Method | Path | Description |
|---|---|---|
| GET | /metrics | includes information on requests |
The Trips API is configured via the variables in the table below.
The value for a configuration variable may be specified via an environment variable (ENV) or as the contents of a file. If the file method is used, then the filename must be the name of the variable. The following describes the precedence used for obtaining a configuration value:
- Content of file located in
/secretspath. Example:/secrets/SQL_USER - Value of environment variable. Example:
$SQL_USER - Default value for configuration variable. Example:
sqladmin
| Name | Required | Type | Default Value | Description |
|---|---|---|---|---|
| PORT | No | ENV | 80 | The port that the API service will listen on. |
| CONFIG_FILES_PATH | No | ENV | /secrets | The base path for file based variables. |
| SQL_USER | Yes | ENV or File | sqladmin | The username for the SQL Server database. |
| SQL_PASSWORD | Yes | ENV or File | The password for the SQL Server database. | |
| SQL_SERVER | Yes | ENV or File | The server name for the SQL Server database. | |
| SQL_DBNAME | Yes | ENV or File | mydrivingDB | The name of the SQL Server database. |
| CREDENTIAL_METHOD | No | ENV | username_and_password | Explicit credential process to access SQL DB. options: username_and_password or managed_identity |
| IDENTITY_CLIENT_ID | No | ENV | The Client ID for a user-assigned identity to an azure resource,required for managed_identity credential process to access SQL DB |
|
| OPENAPI_DOCS_URI | Yes | ENV | The external ip address and port of this api. This is used by the OpenAPI UI. | |
| DEBUG_LOGGING | No | ENV | false | Add debug logging. |
Simple build:
docker build -f Dockerfile -t "tripinsights/trips:1.0" .
To build the image for release"
Bash
docker build --no-cache --build-arg IMAGE_VERSION="1.0" --build-arg IMAGE_CREATE_DATE="`date -u +"%Y-%m-%dT%H:%M:%SZ"`" --build-arg IMAGE_SOURCE_REVISION="`git rev-parse HEAD`" -f Dockerfile -t "tripinsights/trips:1.0" .Powershell
docker build --no-cache --build-arg IMAGE_VERSION="1.0" --build-arg IMAGE_CREATE_DATE="$(Get-Date((Get-Date).ToUniversalTime()) -UFormat '%Y-%m-%dT%H:%M:%SZ')" --build-arg IMAGE_SOURCE_REVISION="$(git rev-parse HEAD)" -f Dockerfile -t "tripinsights/trips:1.0" .To run the image
# Example 1 - Set config values via environment variables
docker run -d -p 8080:80 --name trips -e "SQL_PASSWORD=$SQL_PASSWORD" -e "SQL_SERVER=$SQL_SERVER" -e "OPENAPI_DOCS_URI=http://$EXTERNAL_IP" tripinsights/trips:1.0
# Example 2 - Set configuration via files. Server will expect config values in files like /secrets/SQL_USER.
# The secrets must be mounted from a host volume (eg. $HOST_FOLDER) into the /secrets container volume.
docker run -d -p 8080:80 --name trips -v $HOST_FOLDER:/secrets tripinsights/trips:1.0note: in a
powershellprompt curl is aliased toInvoke-WebRequest. Usecmdprompt or runRemove-Item Alias:curlin powershell.
List all the trips.
curl -i -X GET 'http://localhost:8080/api/trips' Fetch an existing trip with id ea2f7ae0-3cef-49cb-b7d1-ce972113120c.
curl -i -X GET 'http://localhost:8080/api/trips/ea2f7ae0-3cef-49cb-b7d1-ce972113120c' Create a new trip. The id will be autogenerated and returned.
curl -i -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "Name": "Trip 2", "UserId": "hacker2", "RecordedTimeStamp": "2019-07-11T10:00:15.003Z", "EndTimeStamp": "2019-07-11T10:10:15.003Z", "Rating": 90, "IsComplete": false, "HasSimulatedOBDData": false, "AverageSpeed": 0, "FuelUsed": 0, "HardStops": 75, "HardAccelerations": 63, "Distance": 5.95 }' 'http://localhost:8080/api/trips' Update the AverageSpeed and FuelUsed values for an existing trip with id 8f6c3f13-b214-4f8e-917f-1385d5f1b922.
curl -i -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "AverageSpeed": 60, "FuelUsed": 12 }' 'http://localhost:8080/api/trips/8f6c3f13-b214-4f8e-917f-1385d5f1b922'
BROKEN - Overrides all non-provided fields with blanks. This is not how PATCH should behave.Delete the trip for id 8f6c3f13-b214-4f8e-917f-1385d5f1b922
curl -i -X DELETE 'http://localhost:8080/api/trips/8f6c3f13-b214-4f8e-917f-1385d5f1b922'List the trips for user hacker2.
curl -i -X GET 'http://localhost:8080/api/trips/user/hacker2'
BROKEN - getAllTripsForUser - Error scanning Trips: sql: expected 14 destination arguments in Scan, not 15List all the trip points for an existing trip with id ea2f7ae0-3cef-49cb-b7d1-ce972113120c.
curl -i -X GET 'http://localhost:8080/api/trips/ea2f7ae0-3cef-49cb-b7d1-ce972113120c/trippoints'
SLIGHTLY BROKEN - dates not serialising correctlyFetch an existing trip point with id 23dfc028-f84f-4230-b297-88a4bafb6c22 for an existing trip with id ea2f7ae0-3cef-49cb-b7d1-ce972113120c.
curl -i -X GET 'http://localhost:8080/api/trips/ea2f7ae0-3cef-49cb-b7d1-ce972113120c/trippoints/23dfc028-f84f-4230-b297-88a4bafb6c22'
SLIGHTLY BROKEN - dates not serialising correctlyCreate a new trip point for an existing trip with id ea2f7ae0-3cef-49cb-b7d1-ce972113120c.
curl -i -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "TripId": "ea2f7ae0-3cef-49cb-b7d1-ce972113120c", "Latitude": 47.67598, "Longitude": -122.10612, "RecordedTimeStamp": "2018-05-24T10:00:15.003Z", "Sequence": 1, "RPM": 720, "ShortTermFuelBank": -1, "LongTermFuelBank": -4, "ThrottlePosition": 16, "RelativeThrottlePosition": 6, "Runtime": 665, "EngineLoad": 16, "MassFlowRate": 20, "EngineFuelRate": -255, "VIN": "JTEBU5JR9B5046693", "HasOBDData": true, "HasSimulatedOBDData": false }' 'http://localhost:8080/api/trips/ea2f7ae0-3cef-49cb-b7d1-ce972113120c/trippoints'
SLIGHTLY BROKEN - cannot specify VIN in POST.Update the Latitude and Longitude values for an existing trip point with id 23dfc028-f84f-4230-b297-88a4bafb6c22 for an existing trip with id ea2f7ae0-3cef-49cb-b7d1-ce972113120c.
curl -i -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "Latitude": 48.67598, "Longitude": -121.10612 }' 'http://localhost:8080/api/trips/ea2f7ae0-3cef-49cb-b7d1-ce972113120c/trippoints/53dffb4b-91a4-45c2-a10e-a3b3aada3390'
BROKEN - Error while patching Trip Point on the database: mssql: Error converting data type varchar to float..Delete an existing trip point with id 23dfc028-f84f-4230-b297-88a4bafb6c22 for an existing trip with id ea2f7ae0-3cef-49cb-b7d1-ce972113120c.
curl -i -X DELETE 'http://localhost:8080/api/trips/ea2f7ae0-3cef-49cb-b7d1-ce972113120c/trippoints/53dffb4b-91a4-45c2-a10e-a3b3aada3390'Get healthcheck status
curl -i -X GET 'http://localhost:8080/api/trips/healthcheck'