From 21df268af3bb77c6030439bd1c7ff1ac4acf0c2c Mon Sep 17 00:00:00 2001 From: Faiz Abbasi Date: Mon, 5 Nov 2018 13:58:34 -0800 Subject: [PATCH 01/10] Add onDutyMs and driveMs to fleet/drivers/hos_daily_logs --- swagger.json | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/swagger.json b/swagger.json index e250e4b..fb73a6c 100644 --- a/swagger.json +++ b/swagger.json @@ -3671,6 +3671,18 @@ "description": "Milliseconds spent on duty or driving.", "example": 691200 }, + "onDutyMs": { + "type": "number", + "format": "int64", + "description": "Duration in milliseconds that driver was on duty during the requested time range.", + "example": 21600000 + }, + "driveMs": { + "type": "number", + "format": "int64", + "description": "Duration in milliseconds that driver was driving during the requested time range.", + "example": 21600000 + }, "certified": { "type": "boolean", "description": "Whether this HOS day chart was certified by the driver." From 7d459859be8db64c20e9a9802b24c241f3647606 Mon Sep 17 00:00:00 2001 From: Faiz Abbasi Date: Tue, 6 Nov 2018 15:06:46 -0800 Subject: [PATCH 02/10] Add pendingOnDutyMs and pendingDriveMs to fleet/drivers/hos_daily_logs --- swagger.json | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/swagger.json b/swagger.json index fb73a6c..1ccf893 100644 --- a/swagger.json +++ b/swagger.json @@ -3683,6 +3683,18 @@ "description": "Duration in milliseconds that driver was driving during the requested time range.", "example": 21600000 }, + "pendingOnDutyMs": { + "type": "number", + "format": "int64", + "description": "Duration in milliseconds that driver was on duty during the requested time range for pending logs.", + "example": 21600000 + }, + "pendingDriveMs": { + "type": "number", + "format": "int64", + "description": "Duration in milliseconds that driver was driving during the requested time range for pending logs.", + "example": 21600000 + }, "certified": { "type": "boolean", "description": "Whether this HOS day chart was certified by the driver." From 1bda98976fd2b9237d16f42abd9f38e015b51255 Mon Sep 17 00:00:00 2001 From: Derrek Harrison Date: Thu, 8 Nov 2018 10:14:12 -0800 Subject: [PATCH 03/10] swagger: update version for pre-release --- swagger.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/swagger.json b/swagger.json index 1ccf893..2aa37cc 100644 --- a/swagger.json +++ b/swagger.json @@ -2,7 +2,7 @@ "swagger": "2.0", "info": { "title": "Samsara API", - "version": "1.0.0", + "version": "pre-release preview", "description": "# Introduction\n\nSamsara provides API endpoints for interacting with Samsara Cloud, so that you can build powerful applications and custom solutions with sensor data. Samsara has endpoints available to track and analyze sensors, vehicles, and entire fleets.\n\nThe Samsara Cloud API is a [RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer) accessed by an [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) client such as wget or curl, or HTTP libraries of most modern programming languages including python, ruby, java. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We allow you to interact securely with our API from a client-side web application (though you should never expose your secret API key). [JSON](http://www.json.org/) is returned by all API responses, including errors. If you’re familiar with what you can build with a REST API, the following API reference guide will be your go-to resource.\n\nAPI access to the Samsara cloud is available to all Samsara administrators. To start developing with Samsara APIs you will need to [obtain your API keys](#section/Authentication) to authenticate your API requests.\n\nIf you have any questions you can reach out to us on [support@samsara.com](mailto:support@samsara.com)\n\n# Endpoints\n\nAll our APIs can be accessed through HTTP requests to URLs like:\n\n```curl\nhttps://api.samsara.com//\n```\n\nAll our APIs are [versioned](#section/Versioning). If we intend to make breaking changes to an API which either changes the response format or request parameter, we will increment the version.\n\n# Authentication\n\nTo authenticate your API request you will need to include your secret token. You can manage your API tokens in the [Dashboard](https://cloud.samsara.com). They are visible under `Settings->Organization->API Tokens`.\n\nYour API tokens carry many privileges, so be sure to keep them secure. Do not share your secret API tokens in publicly accessible areas such as GitHub, client-side code, and so on.\n\nAuthentication to the API is performed via [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Provide your API token as the basic access_token value in the URL. You do not need to provide a password.\n\n```curl\nhttps://api.samsara.com//?access_token={{access_token}}\n```\n\nAll API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). Calls made over plain HTTP or without authentication will fail.\n\n# Request Methods\n\nOur API endpoints use [HTTP request methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) to specify the desired operation to be performed. The documentation below specified request method supported by each endpoint and the resulting action.\n\n## GET\n\nGET requests are typically used for fetching data (like data for a particular driver).\n\n## POST\n\nPOST requests are typically used for creating or updating a record (like adding new tags to the system). With that being said, a few of our POST requests can be used for fetching data (like current location data of your fleet).\n\n## PUT\n\nPUT requests are typically used for updating an existing record (like updating all devices associated with a particular tag).\n\n## PATCH\n\nPATCH requests are typically used for modifying an existing record (like modifying a few devices associated with a particular tag).\n\n## DELETE\n\nDELETE requests are used for deleting a record (like deleting a tag from the system).\n\n# Response Codes\n\nAll API requests will respond with appropriate [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). Your API client should handle each response class differently.\n\n## 2XX\n\nThese are successful responses and indicate that the API request returned the expected response.\n\n## 4XX\n\nThese indicate that there was a problem with the request like a missing parameter or invalid values. Check the response for specific [error details](#section/Error-Responses). Requests that respond with a 4XX status code, should be modified before retrying.\n\n## 5XX\n\nThese indicate server errors when the server is unreachable or is misconfigured. In this case, you should retry the API request after some delay.\n\n# Error Responses\n\nIn case of a 4XX status code, the body of the response will contain information to briefly explain the error reported. To help debugging the error, you can refer to the following table for understanding the error message.\n\n| Status Code | Message | Description |\n|-------------|----------------|-------------------------------------------------------------------|\n| 401 | Invalid token | The API token is invalid and could not be authenticated. Please refer to the [authentication section](#section/Authentication). |\n| 404 | Page not found | The API endpoint being accessed is invalid. |\n| 400 | Bad request | Default response for an invalid request. Please check the request to make sure it follows the format specified in the documentation. |\n\n# Versioning\n\nAll our APIs are versioned. Our current API version is `v1` and we are continuously working on improving it further and provide additional endpoints. If we intend to make breaking changes to an API which either changes the response format or request parameter, we will increment the version. Thus, you can use our current API version worry free.\n\n# FAQs\n\nCheck out our [responses to FAQs here](https://kb.samsara.com/hc/en-us/sections/360000538054-APIs). Don’t see an answer to your question? Reach out to us on [support@samsara.com](mailto:support@samsara.com)." }, "host": "api.samsara.com", From 28d3cd2c193df6db8779c06a20d74c44ddded4d8 Mon Sep 17 00:00:00 2001 From: Emma Ferguson Date: Wed, 7 Nov 2018 12:28:18 -0800 Subject: [PATCH 04/10] swagger: API spec for dvir POST endpoint --- swagger.json | 420 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 254 insertions(+), 166 deletions(-) diff --git a/swagger.json b/swagger.json index 2aa37cc..08c90e2 100644 --- a/swagger.json +++ b/swagger.json @@ -1013,7 +1013,7 @@ "Fleet","Default" ], "summary": "/fleet/maintenance/dvirs", - "description": "Get the DVIR for the org with the time constraints", + "description": "Get DVIRs for the org within provided time constraints", "operationId": "get_dvirs", "parameters": [ { @@ -1043,7 +1043,7 @@ ], "responses": { "200": { - "description": "DVIR's for the specified group and duration.", + "description": "DVIRs for the specified duration.", "schema": { "$ref": "#/definitions/DvirListResponse" } @@ -1055,6 +1055,32 @@ } } } + }, + "post": { + "tags": [ + "Fleet","Default" + ], + "summary": "/fleet/maintenance/dvirs", + "description": "Create a new dvir, marking a vehicle or trailer safe or unsafe.", + "operationId": "create_dvir", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { "$ref": "#/parameters/createDvirParam" } + ], + "responses": { + "200": { + "description": "Newly created DVIR.", + "schema": { + "$ref": "#/definitions/DvirBase" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } } }, "/fleet/hos_authentication_logs": { @@ -3825,6 +3851,173 @@ "dvirs": { "type": "array", "items": { + "$ref": "#/definitions/DvirBase" + } + } + } + }, + "HosLogsResponse": { + "type": "object", + "properties": { + "logs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "groupId": { + "type": "integer", + "format": "int64", + "description": "ID of the group.", + "example": 101 + }, + "vehicleId": { + "type": "integer", + "format": "int64", + "description": "ID of the vehicle.", + "example": 112 + }, + "driverId": { + "type": "integer", + "format": "int64", + "description": "ID of the driver.", + "example": 444 + }, + "logStartMs": { + "type": "integer", + "format": "int64", + "description": "The time at which the log/HOS status started in UNIX milliseconds.", + "example": 1462881998034 + }, + "statusType": { + "type": "string", + "description": "The Hours of Service status type. One of `OFF_DUTY`, `SLEEPER_BED`, `DRIVING`, `ON_DUTY`, `YARD_MOVE`, `PERSONAL_CONVEYANCE`.", + "example": "OFF_DUTY" + }, + "locCity": { + "type": "string", + "description": "City in which the log was recorded.", + "example": "Ahwatukee" + }, + "locState": { + "type": "string", + "description": "State in which the log was recorded.", + "example": "Arizona" + }, + "locLat": { + "type": "number", + "format": "float", + "description": "Latitude at which the log was recorded.", + "example": 23.413702345 + }, + "locLng": { + "type": "number", + "format": "float", + "description": "Longitude at which the log was recorded.", + "example": -98.502888123 + }, + "locName": { + "type": "string", + "description": "Name of location at which the log was recorded.", + "example": "McLean Site A" + }, + "remark":{ + "type": "string", + "description": "Remark associated with the log entry.", + "example": "Lunch Break" + } + } + } + } + } + }, + "HosAuthenticationLogsResponse": { + "type": "object", + "properties": { + "authenticationLogs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "actionType": { + "type": "string", + "description": "The log type - one of 'signin' or 'signout'", + "example": "signin" + }, + "happenedAtMs": { + "type": "integer", + "format": "int64", + "description": "The time at which the event was recorded in UNIX milliseconds.", + "example": 1462881998034 + }, + "city": { + "type": "string", + "description": "City in which the log was recorded, if applicable.", + "example": "Ahwatukee" + }, + "state": { + "type": "string", + "description": "State in which the log was recorded, if applicable.", + "example": "Arizona" + }, + "addressName": { + "type": "string", + "description": "Address name from the group address book at which the log was recorded, if applicable.", + "example": "Garage Number 3" + }, + "address": { + "type": "string", + "description": "Address at which the log was recorded, if applicable.", + "example": "123 Main St., Ahwatukee, Arizona 85044" + } + } + } + } + } + }, + "ErrorResponse": { + "type": "object", + "description": "Contains the error response when a request fails.", + "properties": { + "status_code": { + "type": "integer", + "description": "HTTP status code returned.", + "format": "int64" + }, + "message": { + "type": "string", + "description": "Error message returned." + } + } + }, + "SensorHistoryResponse": { + "type": "object", + "description": "Contains the results for a sensor history request. Each result contains a timestamp and datapoint for each requested (sensor, field) pair.", + "properties": { + "results": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timeMs": { + "type": "integer", + "description": "Timestamp in UNIX milliseconds.", + "example": 1453449599999 + }, + "series": { + "type": "array", + "description": "List of datapoints, one for each requested (sensor, field) pair.", + "items": { + "type": "integer", + "format": "int64", + "example": 1 + } + } + } + } + } + } + }, + "DvirBase": { "type": "object", "properties": { "id": { @@ -4032,170 +4225,7 @@ } } } - } - } - } - }, - "HosLogsResponse": { - "type": "object", - "properties": { - "logs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "groupId": { - "type": "integer", - "format": "int64", - "description": "ID of the group.", - "example": 101 - }, - "vehicleId": { - "type": "integer", - "format": "int64", - "description": "ID of the vehicle.", - "example": 112 - }, - "driverId": { - "type": "integer", - "format": "int64", - "description": "ID of the driver.", - "example": 444 - }, - "logStartMs": { - "type": "integer", - "format": "int64", - "description": "The time at which the log/HOS status started in UNIX milliseconds.", - "example": 1462881998034 - }, - "statusType": { - "type": "string", - "description": "The Hours of Service status type. One of `OFF_DUTY`, `SLEEPER_BED`, `DRIVING`, `ON_DUTY`, `YARD_MOVE`, `PERSONAL_CONVEYANCE`.", - "example": "OFF_DUTY" - }, - "locCity": { - "type": "string", - "description": "City in which the log was recorded.", - "example": "Ahwatukee" - }, - "locState": { - "type": "string", - "description": "State in which the log was recorded.", - "example": "Arizona" - }, - "locLat": { - "type": "number", - "format": "float", - "description": "Latitude at which the log was recorded.", - "example": 23.413702345 - }, - "locLng": { - "type": "number", - "format": "float", - "description": "Longitude at which the log was recorded.", - "example": -98.502888123 - }, - "locName": { - "type": "string", - "description": "Name of location at which the log was recorded.", - "example": "McLean Site A" - }, - "remark":{ - "type": "string", - "description": "Remark associated with the log entry.", - "example": "Lunch Break" - } - } - } - } - } - }, - "HosAuthenticationLogsResponse": { - "type": "object", - "properties": { - "authenticationLogs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "actionType": { - "type": "string", - "description": "The log type - one of 'signin' or 'signout'", - "example": "signin" - }, - "happenedAtMs": { - "type": "integer", - "format": "int64", - "description": "The time at which the event was recorded in UNIX milliseconds.", - "example": 1462881998034 - }, - "city": { - "type": "string", - "description": "City in which the log was recorded, if applicable.", - "example": "Ahwatukee" - }, - "state": { - "type": "string", - "description": "State in which the log was recorded, if applicable.", - "example": "Arizona" - }, - "addressName": { - "type": "string", - "description": "Address name from the group address book at which the log was recorded, if applicable.", - "example": "Garage Number 3" - }, - "address": { - "type": "string", - "description": "Address at which the log was recorded, if applicable.", - "example": "123 Main St., Ahwatukee, Arizona 85044" - } - } - } - } - } - }, - "ErrorResponse": { - "type": "object", - "description": "Contains the error response when a request fails.", - "properties": { - "status_code": { - "type": "integer", - "description": "HTTP status code returned.", - "format": "int64" - }, - "message": { - "type": "string", - "description": "Error message returned." - } - } - }, - "SensorHistoryResponse": { - "type": "object", - "description": "Contains the results for a sensor history request. Each result contains a timestamp and datapoint for each requested (sensor, field) pair.", - "properties": { - "results": { - "type": "array", - "items": { - "type": "object", - "properties": { - "timeMs": { - "type": "integer", - "description": "Timestamp in UNIX milliseconds.", - "example": 1453449599999 - }, - "series": { - "type": "array", - "description": "List of datapoints, one for each requested (sensor, field) pair.", - "items": { - "type": "integer", - "format": "int64", - "example": 1 - } - } - } - } - } - } + }, "TaggedVehicleBase": { "type": "object", @@ -6068,6 +6098,64 @@ "$ref": "#/definitions/DriverForCreate" } }, + "createDvirParam": { + "name": "createDvirParam", + "description": "DVIR creation body", + "required": true, + "in": "body", + "schema": { + "type": "object", + "required": [ + "vehicleIsSafe", + "inspectionType" + ], + "properties": { + "vehicleIsSafe" : { + "type": "boolean", + "description": "Whether or not this vehicle or trailer is safe to drive.", + "example": true + }, + "inspectionType": { + "type": "string", + "enum": [ + "mechanic" + ], + "description": "Only type 'mechanic' is currently accepted.", + "example": "mechanic" + }, + "vehicleId" : { + "type": "integer", + "description": "Id of vehicle being inspected. Either vehicleId or trailerId must be provided.", + "example": 10 + }, + "trailerId" : { + "type": "integer", + "description": "Id of trailer being inspected. Either vehicleId or trailerId must be provided.", + "example": 11 + }, + "previousDefectsCorrected": { + "type": "boolean", + "description": "Whether any previous defects were corrected. If this vehicle or trailer was previously marked unsafe, and this DVIR marks it as safe, either previousDefectsCorrected or previousDefectsIgnored must be true.", + "example": true + }, + "previousDefectsIgnored": { + "type": "boolean", + "description": "Whether any previous defects were ignored. If this vehicle or trailer was previously marked unsafe, and this DVIR marks it as safe, either previousDefectsCorrected or previousDefectsIgnored must be true.", + "example": false + }, + "odometerMiles": { + "type": "integer", + "description": "The current odometer of the vehicle.", + "example": 38426 + }, + "mechanicNotes": { + "type": "string", + "description": "Any notes from the mechanic.", + "example": "Replaced headlight on passenger side." + } + } + } + }, "routeCreateParam": { "name": "createDispatchRouteParams", "required": true, From 0e7d9fe64988e48518e43b994d335dc51664c511 Mon Sep 17 00:00:00 2001 From: Advith Chelikani Date: Fri, 9 Nov 2018 13:58:10 -0800 Subject: [PATCH 05/10] apidocs: add proposed external id changes for arcbest --- swagger.json | 299 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 208 insertions(+), 91 deletions(-) diff --git a/swagger.json b/swagger.json index 08c90e2..065f0b6 100644 --- a/swagger.json +++ b/swagger.json @@ -568,25 +568,24 @@ } } }, - "/fleet/drivers/{driver_id}": { - "parameters": [ + "/fleet/drivers/{driver_id | external_id}": { + "get": { + "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the driver.", - "type": "integer", - "format": "int64" + "description": "Either the ID of the driver (integer) or corresponding external ID (alphanumeric string). One of these two parameters must be specified to identify the driver.", + "type": "string" } ], - "get": { "tags": [ "Default", "Fleet", "Drivers" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", "description": "Fetch driver by id.", "operationId": "getDriverById", "consumes": [ @@ -610,11 +609,64 @@ } } }, + "patch": { + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "driver_id | external_id", + "in": "path", + "required": true, + "description": "Either the ID of the driver (integer) or corresponding external ID (alphanumeric string). One of these two parameters must be specified to identify the driver.", + "type": "string" + }, + { "$ref": "#/parameters/driverParam" } + ], + "tags": [ + "Default", "Fleet", "Drivers" + ], + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", + "description": "Update driver by id.", + "operationId": "patchDriverById", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "Returns the driver for the given driver_id or external_id.", + "schema": { + "$ref": "#/definitions/CurrentDriver" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, "delete": { + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "driver_id | external_id", + "in": "path", + "required": true, + "description": "Either the ID of the driver (integer) or corresponding external ID (alphanumeric string). One of these two parameters must be specified to identify the driver.", + "type": "string" + } + ], "tags": [ "Default", "Fleet", "Drivers" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", "description": "Deactivate a driver with the given driver_id.", "operationId": "deactivateDriver", "consumes": [ @@ -625,7 +677,7 @@ ], "responses": { "200": { - "description": "Successfully deactivated the driver, which is now referenced by /fleet/drivers/inactive/{driver_id}." + "description": "Successfully deactivated the driver, which is now referenced by /fleet/drivers/inactive/{driver_id | external_id}." }, "default": { "description": "Unexpected error.", @@ -673,25 +725,24 @@ } } }, - "/fleet/drivers/inactive/{driver_id}": { + "/fleet/drivers/inactive/{driver_id | external_id}": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the deactivated driver.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the deactivated driver or corresponding external ID (alphanumeric string).", + "type": "string" } ], "get": { "tags": [ "Default", "Fleet", "Drivers" ], - "summary": "/fleet/drivers/inactive/{driver_id:[0-9]+}", + "summary": "/fleet/drivers/inactive/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", "description": "Fetch deactivated driver by driver_id.", "operationId": "getDeactivatedDriverById", "consumes": [ @@ -719,7 +770,7 @@ "tags": [ "Default", "Fleet", "Drivers" ], - "summary": "/fleet/drivers/inactive/{driver_id:[0-9]+}", + "summary": "/fleet/drivers/inactive/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", "description": "Reactivate the inactive driver having driver_id.", "operationId": "reactivateDriverById", "consumes": [ @@ -817,12 +868,12 @@ } } }, - "/fleet/drivers/{driver_id}/hos_daily_logs": { + "/fleet/drivers/{driver_id | external_id}/hos_daily_logs": { "post": { "tags": [ "Fleet", "Default" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}/hos_daily_logs", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/hos_daily_logs", "description": "Get summarized daily HOS charts for a specified driver.", "operationId": "get_fleet_drivers_hos_daily_logs", "parameters": [ @@ -830,12 +881,11 @@ "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the driver with HOS logs.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the driver with HOS logs or corresponding external ID (alphanumeric string).", + "type": "string" }, { "name": "hosLogsParam", @@ -1561,18 +1611,17 @@ } } }, - "/fleet/drivers/{driver_id}/dispatch/routes": { + "/fleet/drivers/{driver_id | external_id}/dispatch/routes": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the driver with the associated routes.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the driver with the associated routes or corresponding external ID (alphanumeric string).", + "type": "string" } ], "get": { @@ -1581,7 +1630,7 @@ "Fleet", "Routes" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}/dispatch/routes", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", "description": "Fetch all of the dispatch routes for a given driver.", "operationId": "getDispatchRoutesByDriverId", "consumes": [ @@ -1613,7 +1662,7 @@ "tags": [ "Default", "Fleet", "Routes" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}/dispatch/routes", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", "description": "Create a new dispatch route for the driver with driver_id.", "operationId": "createDriverDispatchRoute", "consumes": [ @@ -1641,6 +1690,46 @@ } } }, + "/fleet/vehicles/{vehicle_id | external_id}": { + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "vehicle_id | external_id", + "in": "path", + "required": true, + "description": "ID (integer) of the vehicle or corresponding external ID (alphanumeric string).", + "type": "string" + } + ], + "patch": { + "tags": [ + "Default", + "Fleet" + ], + "summary": "/fleet/vehicles/{vehicle_id | external_id}", + "description": "Updates a vehicle given either a vehicle ID or external ID (alphanumeric string)", + "operationId": "updateVehicle", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "Returns updated vehicle." + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, "/fleet/vehicles/locations": { "parameters": [ { @@ -1691,18 +1780,17 @@ } } }, - "/fleet/vehicles/{vehicle_id}/dispatch/routes": { + "/fleet/vehicles/{vehicle_id | external_id}/dispatch/routes": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "vehicle_id", + "name": "vehicle_id | external_id", "in": "path", "required": true, - "description": "ID of the vehicle with the associated routes.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the vehicle with the associated routes or corresponding external ID (alphanumeric string).", + "type": "string" } ], "get": { @@ -1711,7 +1799,7 @@ "Fleet", "Routes" ], - "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/dispatch/routes", + "summary": "/fleet/vehicles/{{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", "description": "Fetch all of the dispatch routes for a given vehicle.", "operationId": "getDispatchRoutesByVehicleId", "consumes": [ @@ -1726,7 +1814,7 @@ ], "responses": { "200": { - "description": "Returns all of the dispatch routes for the given vehicle_id.", + "description": "Returns all of the dispatch routes for the given vehicle_id or external_id.", "schema": { "$ref": "#/definitions/DispatchRoutes" } @@ -1743,8 +1831,8 @@ "tags": [ "Default", "Fleet", "Routes" ], - "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/dispatch/routes", - "description": "Create a new dispatch route for the vehicle with vehicle_id.", + "summary": "/fleet/vehicles/{{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", + "description": "Create a new dispatch route for the vehicle with vehicle_id or external_id.", "operationId": "createVehicleDispatchRoute", "consumes": [ "application/json" @@ -1771,18 +1859,17 @@ } } }, - "/fleet/vehicles/{vehicle_id}/locations": { + "/fleet/vehicles/{vehicle_id | external_id}/locations": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "vehicle_id", + "name": "vehicle_id | external_id", "in": "path", "required": true, - "description": "ID of the vehicle with the associated routes.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the vehicle with the associated routes or corresponding external ID (alphanumeric string).", + "type": "string" }, { "name": "startMs", @@ -1806,7 +1893,7 @@ "Default", "Fleet" ], - "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/locations", + "summary": "/fleet/vehicles/{{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/locations", "description": "Fetch locations for a given vehicle between a start/end time. The maximum query duration is one hour.", "operationId": "getVehicleLocations", "consumes": [ @@ -1902,18 +1989,17 @@ } } }, - "/fleet/drivers/{driver_id}/documents": { + "/fleet/drivers/{driver_id | external_id}/documents": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the driver for whom the document is created.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the driver for whom the document is created or corresponding external ID (alphanumeric string).", + "type": "string" } ], "post": { @@ -1921,7 +2007,7 @@ "Default", "Fleet" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}/documents", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/documents", "description": "Create a driver document for the given driver.", "operationId": "createDriverDocument", "consumes": [ @@ -3342,6 +3428,45 @@ } } }, + "ExternalDriverResponse" : { + "type": "object", + "description": "Driver object", + "properties": { + "driverId": { + "type": "integer", + "description": "ID of the driver.", + "example": 719 + }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"payrollId": "123", "internalDriverId": "250020"} + } + } + }, + "ExternalVehicleResponse": { + "type": "object", + "description": "Vehicle object", + "properties": { + "vehicle_id": { + "type": "integer", + "format": "int64", + "description": "ID of the vehicle used for the dispatch job.", + "example": 112 + }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"internalVehicleId": "ABFS18600"} + } + } + }, "TripResponse": { "type": "object", "description": "Contains the trips for the vehicle in the requested timeframe. A trip is represented as an object that contains startMs, startLocation, startAddress, startCoordinates, endMs, endLocation, endAddress and endCoordinates.", @@ -3428,10 +3553,8 @@ "description": "Length in meters trip spent on toll roads.", "example": 32000 }, - "driverId": { - "type": "integer", - "description": "ID of the driver.", - "example": 719 + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "startOdometer": { "type": "integer", @@ -3520,6 +3643,9 @@ "format": "int64", "description": "ID of the group if the organization has multiple groups (uncommon).", "example": 101 + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" } } }, @@ -3612,6 +3738,14 @@ "type": "string", "description": "Name of the driver.", "example": "Fred Jacobs" + }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"payrollId": "123", "internalDriverId": "250020"} } } } @@ -4038,21 +4172,7 @@ "example": "pre trip" }, "vehicle": { - "type": "object", - "description": "The vehicle on which DVIR was done.", - "properties": { - "id": { - "type": "integer", - "format": "int64", - "description": "The vehicle id on which DVIR was done.", - "example": 19 - }, - "name": { - "type": "string", - "description": "The vehicle on which DVIR was done.", - "example": "Storer's vehicle 19" - } - } + "$ref": "#/definitions/ExternalVehicleResponse" }, "vehicleDefects": { "type": "array", @@ -4730,17 +4850,11 @@ "description": "ID of the route that this job belongs to.", "example": 55 }, - "driver_id": { - "type": "integer", - "format": "int64", - "description": "ID of the driver assigned to the dispatch job.", - "example": 444 + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, - "vehicle_id": { - "type": "integer", - "format": "int64", - "description": "ID of the vehicle used for the dispatch job.", - "example": 112 + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" }, "fleet_viewer_url": { "type": "string", @@ -4803,17 +4917,11 @@ "start_location_lng" ], "properties": { - "vehicle_id": { - "type": "integer", - "format": "int64", - "description": "ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.", - "example": 444 + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" }, - "driver_id": { - "type": "integer", - "format": "int64", - "description": "ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.", - "example": 555 + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "actual_start_ms": { "type": "integer", @@ -6098,6 +6206,15 @@ "$ref": "#/definitions/DriverForCreate" } }, + "driverParam" : { + "name": "driverParam", + "description": "Driver update body", + "required": true, + "in": "body", + "schema": { + "$ref": "#/definitions/Driver" + } + }, "createDvirParam": { "name": "createDvirParam", "description": "DVIR creation body", @@ -6356,4 +6473,4 @@ "format": "int64" } } -} +} \ No newline at end of file From 325e0ea7130b57fc87c08218a65d56c42ffdb965 Mon Sep 17 00:00:00 2001 From: Advith Chelikani Date: Mon, 12 Nov 2018 17:44:39 -0800 Subject: [PATCH 06/10] arcbest api-docs: remove double curly typos --- swagger.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/swagger.json b/swagger.json index 065f0b6..d8cb5e9 100644 --- a/swagger.json +++ b/swagger.json @@ -1799,7 +1799,7 @@ "Fleet", "Routes" ], - "summary": "/fleet/vehicles/{{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", "description": "Fetch all of the dispatch routes for a given vehicle.", "operationId": "getDispatchRoutesByVehicleId", "consumes": [ @@ -1831,7 +1831,7 @@ "tags": [ "Default", "Fleet", "Routes" ], - "summary": "/fleet/vehicles/{{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", "description": "Create a new dispatch route for the vehicle with vehicle_id or external_id.", "operationId": "createVehicleDispatchRoute", "consumes": [ @@ -1893,7 +1893,7 @@ "Default", "Fleet" ], - "summary": "/fleet/vehicles/{{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/locations", + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/locations", "description": "Fetch locations for a given vehicle between a start/end time. The maximum query duration is one hour.", "operationId": "getVehicleLocations", "consumes": [ From 1e56f635e32024d5bc42cb2466631988041ab293 Mon Sep 17 00:00:00 2001 From: Faiz Abbasi Date: Fri, 2 Nov 2018 11:47:02 -0700 Subject: [PATCH 07/10] Add documentation for unassigned segments endpoints --- swagger.json | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) diff --git a/swagger.json b/swagger.json index d8cb5e9..8822b10 100644 --- a/swagger.json +++ b/swagger.json @@ -1009,6 +1009,176 @@ } } }, + "/fleet/vehicles/{vehicle_id}/unassigned_driving_segments": { + "get": { + "tags": [ + "Fleet", "Default" + ], + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/unassigned_driving_segments", + "description": "Get the unassigned driving segments for a specified range.", + "operationId": "getUnassignedDrivingSegmentsByVehicleId", + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "vehicle_id", + "in": "path", + "required": true, + "description": "ID of the vehicle with the associated unassigned driving segments.", + "type": "integer", + "format": "int64" + }, + { + "name": "start_ms", + "in": "query", + "required": true, + "description": "Beginning of the time range, specified in milliseconds UNIX time.", + "type": "integer", + "format": "int64" + }, + { + "name": "end_ms", + "in": "query", + "required": true, + "description": "End of the time range, specified in milliseconds UNIX time.", + "type": "integer", + "format": "int64" + }, + ], + "responses": { + "200": { + "description": "Unassigned driving segments for provided duration and vehicle.", + "schema": { + "type": "object", + "properties": { + "unassigned_driving_segments": { + "type": "array", + "items": { + "$ref": "#/definitions/UnassignedDrivingSegment" + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/fleet/vehicles/{vehicle_id}/unassigned_driving_segments/{segment_id}": { + "get": { + "tags": [ + "Fleet", "Default" + ], + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/unassigned_driving_segments/{segment_id}", + "description": "Fetch an unassigned driving segment by vehicle ID and segment ID.", + "operationId": "getUnassignedDrivingSegmentByVehicleIdAndSegmentId", + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "vehicle_id", + "in": "path", + "required": true, + "description": "ID of the vehicle with the associated unassigned driving segments.", + "type": "integer", + "format": "int64" + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "ID of the unassigned driving segment.", + "type": "string", + "format": "string" + }, + ], + "responses": { + "200": { + "description": "Unassigned driving segment log for the specified vehicle ID and segment ID.", + "schema": { + "$ref": "#/definitions/UnassignedDrivingSegment" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "patch": { + "tags": [ + "Fleet", "Default" + ], + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/unassigned_driving_segments/{segment_id}", + "description": "Update an unassigned driving segment.", + "operationId": "patchUnassignedDrivingSegment", + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "vehicle_id", + "in": "path", + "required": true, + "description": "ID of the vehicle with the associated unassigned driving segments.", + "type": "integer", + "format": "int64" + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "ID of the unassigned driving segment.", + "type": "string", + "format": "string" + }, + { + "name": "unassignedDrivingSegmentParams", + "required": true, + "in": "body", + "schema": { + "type": "object", + "properties": { + "annotation": { + "type": "string", + "description": "Annotation to give this segment.", + "example": "Drive time" + }, + "driverId": { + "type": "integer", + "format": "int64", + "description": "Driver ID to assign to this segment.", + "example": 719 + } + } + } + } + ], + "responses": { + "200": { + "description": "The unassigned driving segment that was updated.", + "schema": { + "$ref": "#/definitions/UnassignedDrivingSegment" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, "/fleet/hos_logs_summary": { "post": { "tags": [ @@ -3283,6 +3453,47 @@ } } }, + "UnassignedDrivingSegment": { + "type": "object", + "description": "A driving segment that has no associated driver.", + "properties": { + "id": { + "type": "string", + "format": "string", + "example": "MTU0MjE1NzkzNDAwMA", + }, + "vehicle_id": { + "type": "integer", + "format": "int64", + "example": 212014918086169, + }, + "start_ms": { + "type": "integer", + "format": "int64", + "example": 1523059200000, + }, + "end_ms": { + "type": "integer", + "format": "int64", + "example": 1523059200000, + }, + "annotation": { + "type": "string", + "description": "Annotation for the driving segment.", + "example": "Drive time" + }, + "pending_driver_id": { + "type": "integer", + "format": "int64", + "example": 719, + }, + "created_at_ms": { + "type": "integer", + "format": "int64", + "example": 1523059200000, + }, + } + }, "TemperatureResponse": { "type": "object", "description": "Contains the current temperatures of a sensor.", From b52940258171257ec53891e6040eeade9d92dc39 Mon Sep 17 00:00:00 2001 From: Emma Ferguson Date: Thu, 15 Nov 2018 15:07:09 -0800 Subject: [PATCH 08/10] swagger: update dvir POST params Change `isSafe` type bool param to a `safe` type string enum param --- swagger.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/swagger.json b/swagger.json index 8822b10..31e6757 100644 --- a/swagger.json +++ b/swagger.json @@ -6434,14 +6434,18 @@ "schema": { "type": "object", "required": [ - "vehicleIsSafe", + "safe", "inspectionType" ], "properties": { - "vehicleIsSafe" : { - "type": "boolean", + "safe" : { + "type": "string", + "enum": [ + "safe", + "unsafe" + ], "description": "Whether or not this vehicle or trailer is safe to drive.", - "example": true + "example": "safe" }, "inspectionType": { "type": "string", From 44d7bacd2d7cba79f9f08990d08e7285108f002f Mon Sep 17 00:00:00 2001 From: Derrek Harrison Date: Sat, 10 Nov 2018 08:40:16 -0800 Subject: [PATCH 09/10] swagger: add user get, post, patch, delete --- swagger.json | 338 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 338 insertions(+) diff --git a/swagger.json b/swagger.json index 31e6757..6b9ff3c 100644 --- a/swagger.json +++ b/swagger.json @@ -40,9 +40,202 @@ { "name": "Default", "description": "All Samsara API endpoints" + }, + { + "name": "Users", + "description": "Access to user data" } ], "paths": { + "/users": { + "get": { + "tags": [ + "Default", "Users" + ], + "summary": "/users", + "description": "Get all users in the organization.", + "operationId": "list_users", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" } + ], + "responses": { + "200": { + "description": "List of users.", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/User" + } + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "post": { + "tags": [ + "Default", "Users" + ], + "summary": "/users", + "description": "Add a user to the organization.", + "operationId": "create_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { "$ref": "#/parameters/createUserParam" } + ], + "responses": { + "200": { + "description": "User successfully created.", + "schema": { + "$ref": "#/definitions/User" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/users/{user_id}": { + "get": { + "tags": [ + "Default", "Users" + ], + "summary": "/users/{user_id:[0-9]+}", + "description": "Get a user.", + "operationId": "get_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { + "name": "user_id", + "in": "path", + "required": true, + "description": "ID of the user.", + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "User record.", + "schema": { + "$ref": "#/definitions/User" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "delete": { + "tags": [ + "Default", "Users" + ], + "summary": "/users/{user_id:[0-9]+}", + "description": "Remove a user from the organization.", + "operationId": "delete_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { + "name": "user_id", + "in": "path", + "required": true, + "description": "ID of the user.", + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "The user was successfully removed." + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "patch": { + "tags": [ + "Default", "Users" + ], + "summary": "/users/{user_id:[0-9]+}", + "description": "Update some fields on a user. Only fields to be changed need to be supplied. Note that if you change an object or collection, you must supply the complete collection. For example, to add a tag role to a user, you must specify all tag roles that the user should have.", + "operationId": "update_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { "$ref": "#/parameters/updateUserParam" }, + { + "name": "user_id", + "in": "path", + "required": true, + "description": "ID of the user.", + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "User successfully updated.", + "schema": { + "$ref": "#/definitions/User" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "put": { + "tags": [ + "Default", "Users" + ], + "summary": "/users/{user_id:[0-9]+}", + "description": "Replace all fields on a user with the supplied fields. Any fields not supplied will be set to null.", + "operationId": "replace_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { "$ref": "#/parameters/createUserParam" }, + { + "name": "user_id", + "in": "path", + "required": true, + "description": "ID of the user.", + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "User successfully created.", + "schema": { + "$ref": "#/definitions/User" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, "/sensors/list": { "post": { "tags": [ @@ -6266,6 +6459,122 @@ "example": "111-222-3344" } } + }, + "UserBase": { + "type": "object", + "properties": { + "name" : { + "type": "string", + "description": "The first and last name of the user.", + "example": "Jane Doe" + }, + "email": { + "type": "string", + "description": "The email address of this user.", + "example": "user@company.com" + }, + "authType": { + "type": "string", + "enum": [ + "basic", + "saml" + ], + "description": "The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration." + }, + "organizationRole" : { + "type": "string", + "description": "The name of the role the user is assigned to for the organization. This will be blank for users that only have access to specific tags.", + "example": "Read-Only Admin" + } + } + }, + "UpsertUserBase": { + "allOf": [ + { + "$ref": "#/definitions/UserBase" + }, + { + "type": "object", + "properties": { + "tagRoles" : { + "type": "array", + "description": "If specified, the user will be a tag administrator for these tags. If left blank, the user has access to the entire organization.", + "items": { + "type": "object", + "properties": { + "tagName": { + "type": "string", + "description": "The name of the tag to grant this user access to.", + "example": "North Carolina Distribution" + }, + "role" : { + "type": "string", + "description": "The name of the role the user is assigned to for this tag. This must match one of the preset roles or the name of a custom role in the organization. This value is case insensitive.", + "example": "Read-Only Admin" + } + } + } + } + } + } + ] + }, + "User": { + "allOf": [ + { + "$ref": "#/definitions/UserBase" + }, + { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The ID of the User record.", + "example": 123 + }, + "tagRoles" : { + "type": "array", + "description": "The specific tags this user has access to. This will be blank for users that have full access to the organization.", + "items": { + "$ref": "#/definitions/UserTagRole" + } + } + } + } + ] + }, + "UserTagRole": { + "type": "object", + "properties": { + "tag": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The ID of this tag.", + "example": 12345 + }, + "name": { + "type": "string", + "description": "Name of this tag.", + "example": "North Carolina Distribution" + }, + "parentTagId": { + "type": "integer", + "format": "int64", + "description": "The ID of this tag.", + "example": 12345 + } + } + }, + "role": { + "type": "string", + "description": "The role the user has been granted on this tag.", + "example": "Full Admin" + } + } } }, "parameters": { @@ -6686,6 +6995,35 @@ "in": "query", "type": "integer", "format": "int64" + }, + "createUserParam": { + "name": "user", + "description": "User properties. Only one of organizationRole or tagRoles is required.", + "required": true, + "in": "body", + "schema": { + "type": "object", + "required": [ + "name", + "email", + "authType" + ], + "allOf": [ + { + "$ref": "#/definitions/UpsertUserBase" + } + ] + + } + }, + "updateUserParam": { + "name": "user", + "description": "User properties. Note that when updating tagRoles, the complete list of tag roles must be supplied for the user. To delete all tag roles set the value to null or an empty array.", + "required": true, + "in": "body", + "schema": { + "$ref": "#/definitions/UpsertUserBase" + } } } } \ No newline at end of file From e0b6e1e3b2a8ccd3e94c1c704fd3d73c66f407b7 Mon Sep 17 00:00:00 2001 From: Advith Chelikani Date: Wed, 28 Nov 2018 12:21:41 -0800 Subject: [PATCH 10/10] docs: add driver and vehicle dict with external ids in response payloads --- swagger.json | 123 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 114 insertions(+), 9 deletions(-) diff --git a/swagger.json b/swagger.json index 6b9ff3c..365efa8 100644 --- a/swagger.json +++ b/swagger.json @@ -3449,6 +3449,14 @@ "format": "int64", "example": 112 }, + "externalIds": { + "type": "object", + "description": "Map of all external ids for vehicle", + "additionalProperties": { + "type": "string" + }, + "example": {"maintenanceId": "123", "internalVehicleId": "BNUN2798"} + }, "name": { "type": "string", "description": "Name of the vehicle.", @@ -3496,6 +3504,14 @@ "format": "int64", "example": 112 }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"maintenanceId": "123", "internalVehicleId": "BNUN2798"} + }, "name": { "type": "string", "description": "Name of the vehicle.", @@ -3560,6 +3576,14 @@ "format": "int64", "example": 112 }, + "externalIds": { + "type": "object", + "description": "Map of all external ids for vehicle", + "additionalProperties": { + "type": "string" + }, + "example": {"maintenanceId": "123", "internalVehicleId": "BNUN2798"} + }, "j1939": { "type": "object", "description": "J1939 based data. Null if no data is available.", @@ -3660,6 +3684,9 @@ "format": "int64", "example": 212014918086169, }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" + }, "start_ms": { "type": "integer", "format": "int64", @@ -3832,11 +3859,21 @@ } } }, + "VehicleIdResponse": { + "type": "integer", + "description": "ID of the vehicle.", + "example": 444 + }, + "DriverIdResponse": { + "type": "integer", + "description": "ID of the driver.", + "example": 719 + }, "ExternalDriverResponse" : { "type": "object", "description": "Driver object", "properties": { - "driverId": { + "id": { "type": "integer", "description": "ID of the driver.", "example": 719 @@ -3855,11 +3892,31 @@ "type": "object", "description": "Vehicle object", "properties": { - "vehicle_id": { + "id": { + "type": "integer", + "format": "int64", + "description": "ID of the vehicle.", + "example": 444 + }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"internalVehicleId": "CITY320025"} + } + } + }, + "ExternalCurrentVehicleResponse": { + "type": "object", + "description": "Vehicle object", + "properties": { + "id": { "type": "integer", "format": "int64", "description": "ID of the vehicle used for the dispatch job.", - "example": 112 + "example": 879 }, "externalIds" : { "type": "object", @@ -3957,6 +4014,9 @@ "description": "Length in meters trip spent on toll roads.", "example": 32000 }, + "driverId": { + "$ref": "#/definitions/DriverIdResponse" + }, "driver": { "$ref": "#/definitions/ExternalDriverResponse" }, @@ -4042,12 +4102,21 @@ "description": "ID of the vehicle assigned to the driver for static vehicle assignments. (uncommon).", "example": 444 }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" + }, "groupId": { "type": "integer", "format": "int64", "description": "ID of the group if the organization has multiple groups (uncommon).", "example": 101 }, + "driverId": { + "type": "integer", + "format": "int64", + "description": "ID of the driver", + "example": 719 + }, "driver": { "$ref": "#/definitions/ExternalDriverResponse" } @@ -4098,7 +4167,10 @@ "format": "int64", "description": "ID of the vehicle that this driver is currently assigned to. Omitted if there is no current vehicle assignment for this driver.", "example": 879 - } + }, + "currentVehicle": { + "$ref": "#/definitions/ExternalCurrentVehicleResponse" + }, } }, { @@ -4168,7 +4240,10 @@ "type": "integer", "format": "int64", "description": "ID of the driver.", - "example": 444 + "example": 719 + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "driverName": { "type": "string", @@ -4313,7 +4388,10 @@ "type": "integer", "format": "int64", "description": "ID of the driver.", - "example": 444 + "example": 719 + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "driverName": { "type": "string", @@ -4412,13 +4490,19 @@ "type": "integer", "format": "int64", "description": "ID of the vehicle.", - "example": 112 + "example": 444 + }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" }, "driverId": { "type": "integer", "format": "int64", "description": "ID of the driver.", - "example": 444 + "example": 719 + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "logStartMs": { "type": "integer", @@ -5254,9 +5338,15 @@ "description": "ID of the route that this job belongs to.", "example": 55 }, + "driver_id": { + "$ref": "#/definitions/DriverIdResponse" + }, "driver": { "$ref": "#/definitions/ExternalDriverResponse" }, + "vehicle_id": { + "$ref": "#/definitions/VehicleIdResponse" + }, "vehicle": { "$ref": "#/definitions/ExternalVehicleResponse" }, @@ -5321,9 +5411,15 @@ "start_location_lng" ], "properties": { + "vehicle_id": { + "$ref": "#/definitions/VehicleIdResponse" + }, "vehicle": { "$ref": "#/definitions/ExternalVehicleResponse" }, + "driver_id": { + "$ref": "#/definitions/DriverIdResponse" + }, "driver": { "$ref": "#/definitions/ExternalDriverResponse" }, @@ -5971,6 +6067,9 @@ "description": "Vehicle associated with the harsh event", "example": 212014918086169 }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" + }, "timestampMs": { "type": "integer", "description": "Timestamp that the harsh event occurred in Unix milliseconds since epoch", @@ -6290,6 +6389,9 @@ "description": "ID of the driver for whom the document is submitted", "example": 555 }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" + }, "driverCreatedAtMs": { "type": "integer", "format": "int64", @@ -6305,7 +6407,10 @@ "type": "integer", "format": "int64", "description": "VehicleID of the driver at document creation.", - "example": 222 + "example": 444 + }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" }, "fields": { "description": "The fields associated with this document.",