diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..cb2845b Binary files /dev/null and b/.DS_Store differ diff --git a/spec/.DS_Store b/spec/.DS_Store new file mode 100644 index 0000000..b9c7676 Binary files /dev/null and b/spec/.DS_Store differ diff --git a/spec/components/parameters/fromDate.yaml b/spec/components/parameters/fromDate.yaml index 65aefcc..da14c64 100644 --- a/spec/components/parameters/fromDate.yaml +++ b/spec/components/parameters/fromDate.yaml @@ -4,4 +4,4 @@ description: Start date of the query range in ISO format. Must be within 48 hour example: "2019-11-15T08:00:00Z" required: true schema: - type: ISO string + type: ISO string (UTC time) diff --git a/spec/components/parameters/toDate.yaml b/spec/components/parameters/toDate.yaml index 8a8044b..c827c07 100644 --- a/spec/components/parameters/toDate.yaml +++ b/spec/components/parameters/toDate.yaml @@ -5,4 +5,4 @@ description: | example: "2019-11-16T08:00:00Z" required: true schema: - type: ISO string + type: ISO string (UTC time) diff --git a/spec/components/schemas/objects/BatteryVoltage.yaml b/spec/components/schemas/objects/BatteryVoltage.yaml new file mode 100644 index 0000000..dacf580 --- /dev/null +++ b/spec/components/schemas/objects/BatteryVoltage.yaml @@ -0,0 +1,10 @@ +type: object +properties: + messageId: + $ref: "#/components/schemas/messageId" + asset: + $ref: "#/components/schemas/asset" + recordedAt: + $ref: "#/components/schemas/recordedAt" + voltage: + $ref: "#/components/schemas/voltage" diff --git a/spec/components/schemas/objects/BatteryVoltageArray.yaml b/spec/components/schemas/objects/BatteryVoltageArray.yaml new file mode 100644 index 0000000..26be872 --- /dev/null +++ b/spec/components/schemas/objects/BatteryVoltageArray.yaml @@ -0,0 +1,3 @@ +type: array +items: + $ref: "#/components/schemas/BatteryVoltage" diff --git a/spec/components/schemas/objects/CombinedMileage.yaml b/spec/components/schemas/objects/CombinedMileage.yaml new file mode 100644 index 0000000..ff9fcc4 --- /dev/null +++ b/spec/components/schemas/objects/CombinedMileage.yaml @@ -0,0 +1,6 @@ +type: object +properties: + GPSMileage: + $ref: "#/components/schemas/Mileage" + mileage: + $ref: "#/components/schemas/Mileage" \ No newline at end of file diff --git a/spec/components/schemas/objects/DTC.yaml b/spec/components/schemas/objects/DTC.yaml new file mode 100644 index 0000000..cc66f1c --- /dev/null +++ b/spec/components/schemas/objects/DTC.yaml @@ -0,0 +1,10 @@ +type: object +properties: + messageId: + $ref: "#/components/schemas/messageId" + asset: + $ref: "#/components/schemas/asset" + recordedAt: + $ref: "#/components/schemas/recordedAt" + rawData: + $ref: "#/components/schemas/rawData" diff --git a/spec/components/schemas/objects/DTCArray.yaml b/spec/components/schemas/objects/DTCArray.yaml new file mode 100644 index 0000000..d49ead9 --- /dev/null +++ b/spec/components/schemas/objects/DTCArray.yaml @@ -0,0 +1,3 @@ +type: array +items: + $ref: "#/components/schemas/DTC" diff --git a/spec/components/schemas/objects/Vin.yaml b/spec/components/schemas/objects/Vin.yaml new file mode 100644 index 0000000..f3e35c2 --- /dev/null +++ b/spec/components/schemas/objects/Vin.yaml @@ -0,0 +1,10 @@ +type: object +properties: + messageId: + $ref: "#/components/schemas/messageId" + asset: + $ref: "#/components/schemas/asset" + recordedAt: + $ref: "#/components/schemas/recordedAt" + vin: + $ref: "#/components/schemas/vin" diff --git a/spec/components/schemas/objects/VinArray.yaml b/spec/components/schemas/objects/VinArray.yaml new file mode 100644 index 0000000..2b1dd48 --- /dev/null +++ b/spec/components/schemas/objects/VinArray.yaml @@ -0,0 +1,3 @@ +type: array +items: + $ref: "#/components/schemas/Vin" diff --git a/spec/components/schemas/rawData.yaml b/spec/components/schemas/rawData.yaml new file mode 100644 index 0000000..5f46f1e --- /dev/null +++ b/spec/components/schemas/rawData.yaml @@ -0,0 +1,3 @@ +type: string +description: Raw DTC code information in stringified JSON format. +example: [{\"mode\":3,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}] \ No newline at end of file diff --git a/spec/components/schemas/vin.yaml b/spec/components/schemas/vin.yaml new file mode 100644 index 0000000..2c92a09 --- /dev/null +++ b/spec/components/schemas/vin.yaml @@ -0,0 +1,3 @@ +description: Vehicle Identification Number (VIN) of the car +type: string +example: WP0ZZZ99ZTS392124 diff --git a/spec/components/schemas/voltage.yaml b/spec/components/schemas/voltage.yaml new file mode 100644 index 0000000..1b744ca --- /dev/null +++ b/spec/components/schemas/voltage.yaml @@ -0,0 +1,3 @@ +type: double +description: Battery voltage of the car's battery +example: 12.09 \ No newline at end of file diff --git a/spec/openapi.yaml b/spec/openapi.yaml index 74b36f1..d377998 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -27,10 +27,37 @@ tags: - name: Fuel description: Get current and historical fuel information for an IMEI. - name: Mileage - description: Get current and historical mileage information for an IMEI. + description: Get current and historical mileage information for an IMEI. \ + You will find two values here, the mileage reported by the vehicle (`Mileage`) and mileage calculated by the autoSense device (`GPS Mileage`) - name: PlugUnplug description: | Retrieve actual or historical information whether the MDI device is connected to the car's OBD port. \ A new record is created each time the status of the devices changes from `plugged` or `unplugged`. + - name: Error Codes + description: | + Error codes reported by the vehicle and malfunction indicator light status (MIL). servers: - url: 'https://nebula.service.autosense.ch/api/v1' + +x-tagGroups: + - name: VIN + tags: + - VIN + - name: Plug Unplug + tags: + - PlugUnplug + - name: Fuel + tags: + - Fuel + - name: Mileage + tags: + - Mileage + - GPS Mileage + - Combined Mileage + - name: Error Codes + tags: + - DTC + - MIL + - name: Battery Voltage + tags: + - Battery Voltage diff --git a/spec/paths/asset@{assetId}@batteryVoltage.yaml b/spec/paths/asset@{assetId}@batteryVoltage.yaml new file mode 100644 index 0000000..d9be294 --- /dev/null +++ b/spec/paths/asset@{assetId}@batteryVoltage.yaml @@ -0,0 +1,28 @@ +parameters: + - $ref: "#/components/parameters/assetId" + +get: + tags: + - Battery Voltage + summary: Get Battery Voltage + description: | + Returns the latest recorded basttery voltage of the vehicle. + operationId: getBatteryVoltage + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/BatteryVoltage" + example: + messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + voltage: 12.09 + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@batteryVoltage@history.yaml b/spec/paths/asset@{assetId}@batteryVoltage@history.yaml new file mode 100644 index 0000000..78ce45b --- /dev/null +++ b/spec/paths/asset@{assetId}@batteryVoltage@history.yaml @@ -0,0 +1,34 @@ +parameters: + - $ref: "#/components/parameters/assetId" + - $ref: "#/components/parameters/fromDate" + - $ref: "#/components/parameters/toDate" + +get: + tags: + - Battery Voltage + summary: Get Battery Voltage history + description: | + Returns an array of basttery voltage records for the car's battery. + operationId: getBatteryVoltageHistory + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/BatteryVoltageArray" + example: + - messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + voltage: 12.09 + - messageId: mdi-1313382935323227352 + asset: "3516220738006655" + recordedAt": "2019-12-04T06:54:51Z" + voltage: 11.491 + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@combined-mileage.yaml b/spec/paths/asset@{assetId}@combined-mileage.yaml new file mode 100644 index 0000000..66524ff --- /dev/null +++ b/spec/paths/asset@{assetId}@combined-mileage.yaml @@ -0,0 +1,35 @@ +parameters: + - $ref: "#/components/parameters/assetId" + +get: + tags: + - Combined Mileage + summary: Get combined mileage + description: | + Returns the latest recorded mileage information for a given IMEI. + This endpoint provides both the mileage reported by the vehicle and the mileage calculated by the onboard autoSense device GPS. + operationId: getCombinedMileage + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/CombinedMileage" + example: + GPSMileage: + messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + mileage: 12500 + mileage: + messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + mileage: 12500 + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@dtc.yaml b/spec/paths/asset@{assetId}@dtc.yaml new file mode 100644 index 0000000..e01f2a3 --- /dev/null +++ b/spec/paths/asset@{assetId}@dtc.yaml @@ -0,0 +1,28 @@ +parameters: + - $ref: "#/components/parameters/assetId" + +get: + tags: + - DTC + summary: Get DTC codes + description: | + Returns the latest recorded Diagnostics Trouble Codes (DTC) from the vehicle's onboard diagnostics system in a stringified JSON format. + operationId: getDtc + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/DTC" + example: + messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + rawData: "[{\"mode\":3,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@dtc@history.yaml b/spec/paths/asset@{assetId}@dtc@history.yaml new file mode 100644 index 0000000..ae5b651 --- /dev/null +++ b/spec/paths/asset@{assetId}@dtc@history.yaml @@ -0,0 +1,34 @@ +parameters: + - $ref: "#/components/parameters/assetId" + - $ref: "#/components/parameters/fromDate" + - $ref: "#/components/parameters/toDate" + +get: + tags: + - DTC + summary: Get DTC codes history + description: | + Returns an array of the recorded Diagnostics Trouble Codes (DTC) from the vehicle's onboard diagnostics system in a stringified JSON format. + operationId: getDtc + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/DTCArray" + example: + - messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + rawData: "[{\"mode\":7,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]" + - messageId: mdi-1313382935323227352 + asset: "3516220738006655" + recordedAt": "2019-12-04T06:54:51Z" + rawData: "[{\"mode\":7,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@fuel@history?fromDate=date1&toDate=date2.yaml b/spec/paths/asset@{assetId}@fuel@history.yaml similarity index 100% rename from spec/paths/asset@{assetId}@fuel@history?fromDate=date1&toDate=date2.yaml rename to spec/paths/asset@{assetId}@fuel@history.yaml diff --git a/spec/paths/asset@{assetId}@mil.yaml b/spec/paths/asset@{assetId}@mil.yaml new file mode 100644 index 0000000..a735ab1 --- /dev/null +++ b/spec/paths/asset@{assetId}@mil.yaml @@ -0,0 +1,28 @@ +parameters: + - $ref: "#/components/parameters/assetId" + +get: + tags: + - MIL + summary: Get MIL codes + description: | + Returns the latest recorded Malfunction Indicator Light (MIL) codes from the vehicle's onboard diagnostics system in a stringified JSON format. + operationId: getMil + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/DTC" + example: + messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + rawData: "[{\"mode\":3,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@mil@history.yaml b/spec/paths/asset@{assetId}@mil@history.yaml new file mode 100644 index 0000000..7bf2946 --- /dev/null +++ b/spec/paths/asset@{assetId}@mil@history.yaml @@ -0,0 +1,34 @@ +parameters: + - $ref: "#/components/parameters/assetId" + - $ref: "#/components/parameters/fromDate" + - $ref: "#/components/parameters/toDate" + +get: + tags: + - MIL + summary: Get MIL codes history + description: | + Returns an array of the recorded Malfunction Indicator Light (MIL) codes from the vehicle's onboard diagnostics system in a stringified JSON format. + operationId: getMilHistory + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/DTCArray" + example: + - messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + : "[{\"mode\":7,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]" + - messageId: mdi-1313382935323227352 + asset: "3516220738006655" + recordedAt": "2019-12-04T06:54:51Z" + : "[{\"mode\":7,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@mileage.yaml b/spec/paths/asset@{assetId}@mileage.yaml index 518e440..0a5ff86 100644 --- a/spec/paths/asset@{assetId}@mileage.yaml +++ b/spec/paths/asset@{assetId}@mileage.yaml @@ -7,6 +7,7 @@ get: summary: Get mileage description: | Returns the latest recorded mileage information for a given IMEI. + This endpoint refers to the mileage reported by the vehicle. operationId: getMileage security: - basicAuth: [] diff --git a/spec/paths/asset@{assetId}@mileage@history?fromDate=date1&toDate=date2.yaml b/spec/paths/asset@{assetId}@mileage@history.yaml similarity index 100% rename from spec/paths/asset@{assetId}@mileage@history?fromDate=date1&toDate=date2.yaml rename to spec/paths/asset@{assetId}@mileage@history.yaml diff --git a/spec/paths/asset@{assetId}@obdmileage.yaml b/spec/paths/asset@{assetId}@obdmileage.yaml new file mode 100644 index 0000000..3d31b43 --- /dev/null +++ b/spec/paths/asset@{assetId}@obdmileage.yaml @@ -0,0 +1,29 @@ +parameters: + - $ref: "#/components/parameters/assetId" + +get: + tags: + - GPS Mileage + summary: Get GPS mileage + description: | + Returns the latest recorded GPS mileage information for a given IMEI. + This endpoint refers to the mileage calculated by the device's GPS. + operationId: getGPSMileage + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Mileage" + example: + messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + mileage: 11560 + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@obdmileage@history.yaml b/spec/paths/asset@{assetId}@obdmileage@history.yaml new file mode 100644 index 0000000..96e8973 --- /dev/null +++ b/spec/paths/asset@{assetId}@obdmileage@history.yaml @@ -0,0 +1,35 @@ +parameters: + - $ref: "#/components/parameters/assetId" + - $ref: "#/components/parameters/fromDate" + - $ref: "#/components/parameters/toDate" + +get: + tags: + - GPS Mileage + summary: Get GPS mileage history + description: | + Returns an array of GPS mileage messages for a given IMEI within the provided date range. + This endpoint refers to the mileage calculated by the device's GPS. + operationId: getMileageHistory + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/MileageArray" + example: + - messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + mileage: 12500 + - messageId: mdi-1313382935323227382 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:55:51Z" + mileage: 12505 + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" diff --git a/spec/paths/asset@{assetId}@plugUnplug@history?fromDate=date1&toDate=date2.yaml b/spec/paths/asset@{assetId}@plugUnplug@history.yaml similarity index 100% rename from spec/paths/asset@{assetId}@plugUnplug@history?fromDate=date1&toDate=date2.yaml rename to spec/paths/asset@{assetId}@plugUnplug@history.yaml diff --git a/spec/paths/asset@{assetId}@vin.yaml b/spec/paths/asset@{assetId}@vin.yaml new file mode 100644 index 0000000..c09e290 --- /dev/null +++ b/spec/paths/asset@{assetId}@vin.yaml @@ -0,0 +1,29 @@ +parameters: + - $ref: "#/components/parameters/assetId" + +get: + tags: + - VIN + summary: Get VIN + description: | + Returns the latest recorded Vehicle Identification Number (VIN) for a given IMEI. + operationId: getVin + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/Vin" + example: + messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + vin: WP0ZZZ99ZTS392124 + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound" + diff --git a/spec/paths/asset@{assetId}@vin@history.yaml b/spec/paths/asset@{assetId}@vin@history.yaml new file mode 100644 index 0000000..e85026c --- /dev/null +++ b/spec/paths/asset@{assetId}@vin@history.yaml @@ -0,0 +1,34 @@ +parameters: + - $ref: "#/components/parameters/assetId" + - $ref: "#/components/parameters/fromDate" + - $ref: "#/components/parameters/toDate" + +get: + tags: + - VIN + summary: Get VIN history + description: | + Returns an array of Vehicle Identification Number (VIN) for a given IMEI within the provided date range. + operationId: getVINHistory + security: + - basicAuth: [] + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/VinArray" + example: + - messageId: mdi-1313382935323227381 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:54:51Z" + vin: WP0ZZZ99ZTS392124 + - messageId: mdi-1313382935323227382 + asset: "3516220738006655" + recordedAt": "2019-12-04T05:55:51Z" + vin: WP0ZZZ99ZTS392124 + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/DataNotFound"