vinli / docs Goto Github PK

Report Card grades are letter grades (A,B,C,D,F) only.

For "Get a Device" the Response shows links: Self, Groups, Vehicles, LatestVehicle". When I look at the device.js file, it shows links: Self, Vehicles, Latest Vehicle. I'm thinking that Groups should be removed from the doc.

Authentication section, 3rd paragraph: Each request must include the App ID and App Secret in the Authentorization... should be spelled Authorization

Pagination does not sort in chronological order for resource list pagination or oldest to most recent order for streaming pagination. Instead, it has been decided to use time series ordering where the first item in the list should be the "latest or most recent. For example - vehicles are returned in order based on most recently used.
A request to list all vehicles for a device would look like this:
GET https://platform-dev.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b21/vehicles

In the response, the first vehicle in the list has the same vehicleID as sending the request with the "_latest" parameter.

GET https://platform-dev.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b21/vehicles/_latest

In the response, the vehicleID is the same as the first vehicle in the results from the List all vehicles request"

The line reads: Enterprise-level applications, which require specific approval from Vinli, are able to manage a specific block of devices that are "owned" by the application. I don't see where the concept of a "block" of device IDs exists. If it does, I would expect that Device IDs being returned from a List all Devices request would be identified by their block, but there is no block attribute associated with a device or that pagination provides organization based on blocks for an enterprise application.

Get the list of all DTC Codes for a Device - in the response, scroll down to the pagination meta data.
There are 2 "limit" parameters - on is set to the default and the other is set to the maximum

In the Response, meta data show limit set to 50. Since it wasn't set on the request, it should be show the default value of 20 and not 50, right?

Inconsistency between doc and response. See response below:

The Response pagination has the parameter "remaining". In the platform's transaction service, the "get all transactions" response also uses streaming pagination, however it has parameter " remainingCount" and not "remaining". Which one is correct?

Need to add:

  "deviceId"
  "preview"
  "stats": {
    "averageLoad": null,
    "averageMovingSpeed": null,
    "averageSpeed": null,
    "distance": null,
    "distanceByGPS": null,
    "distanceByVSS": null,
    "duration": null,
    "fuelConsumed": null,
    "fuelEconomy": null,
    "hardAccelCount": null,
    "hardBrakeCount": null,
    "locationCount": null,
    "maxSpeed": null,
    "messageCount": null,
    "stdDevMovingSpeed": null,
    "stopCount": null
  },
  "links": {
    "device": "https://platform-dev.vin.li/api/v1/devices/64013359-093a-4ed1-bd5f-cb47deaea262",
    "messages": "https://telemetry-dev.vin.li/api/v1/devices/64013359-093a-4ed1-bd5f-cb47deaea262/messages?since=1438723715937&until=1439319581076",
    "events": "https://events-dev.vin.li/api/v1/devices/64013359-093a-4ed1-bd5f-cb47deaea262/events?since=1438723715937&until=1439319581076"

Need to remove link: "snapshots" : "https://trips.vin.li/api/v1/trips/e960a385-0ced-4654-8404-3238e147ad45/snapshots"

Need to update pagination for time series

There isn't any verbiage to explain geospatial rules. At a minimum it is important to know the unit of measure for radius (measured in meters).

The response needs to be updated to include:

deviceId, startPoint, stopPoint, preview, orphanedAt, and
"stats": {
"averageLoad": null,
"averageMovingSpeed": null,
"averageSpeed": null,
"distance": null,
"distanceByGPS":null,
"distanceByVss": null,
"duration": null,
"fuelConsumed": null,
"fuelEconomy": null,
"hardAccelCount": null,
"hardBrakeCount": null,
"locationCount": null,
"maxSpeed": null,
"messageCount": null,
"stdDevMovingSpeed": null,
"stopCount": null

Links needs to be updated to include:
device, vehicle, messages, and events.

Remove the "snapshots" link

Trip/Trips vs trip/trips

In the docs, the number of hard stops is referenced as "hardStopCount" but in the actual response from trips-dev.vin.li, I am getting "hardBreakCount".

Device Report Cards use since & until parameters using the iso 8601 z and UNIX formats. The "weekly" iso 8601 format is no longer being used. Using since and until is used to specify any date range

Notification Payload section - verbiage below the example, second paragraph starts like this and has 2 typos - Notification and representation:

In the example above, the Subscription triggered is associated with a Rule. In this case, additional information is made available in the Notificaiton including a reprsentation of the Rule in the meta property.

The response needs to be updated to include:

deviceId, startPoint, stopPoint, preview, orphanedAt, and
"stats": {
"averageLoad": null,
"averageMovingSpeed": null,
"averageSpeed": null,
"distance": null,
"distanceByGPS":null,
"distanceByVss": null,
"duration": null,
"fuelConsumed": null,
"fuelEconomy": null,
"hardAccelCount": null,
"hardBrakeCount": null,
"locationCount": null,
"maxSpeed": null,
"messageCount": null,
"stdDevMovingSpeed": null,
"stopCount": null

Links needs to be updated to include:
device, messages, and events.

Device Service, first paragraph - 2nd line - Each Vinil Basic... should be "Vinli"

Second paragraph:
t's important to note that trips are sometimes created asyncrhonously--either because they have to be constructed by post-processing or after bulk data upload for a given device.

Should be spelled asynchronously

Last sentence: ...but it's import to not that only those parameters with a decimal dataType are usable in Rules. - "not" should be "note"

Doc states: More information about these parameters can be found in the "Parameters" section above, but it is important...

Where is the parameters section?

"name" was added to the code, but it hasn't been updated in the docs

List All of a Device's Vehicles

Returns the vehicles associated with the given device in chronological order.

Update to read ...given device in time series order.

Incorrect URI

Documentation URI: https://diagnostics.vin.li
Actual URI: https://diagnostic.vin.li

Incorrect Response (GET /api/v1/codes?number=P0001)

Documentation Response

{
  "code" : {
    "make": "generic",
    "twoByte": {
      "number": "P0001",
      "description": "Fuel Volume Regulator Control Circuit/Open"
    },
    "threeByte": {
      "number": "P0001",
      "ftb": "13",
      "fault": "Circuit Open",
      "description": "Fuel Volume Regulator Control"
    }
  }
}

Actual Response

{
  "codes": [
    {
      "id": "2db60bc5-0548-43ee-91c0-c34d59ce71ce",
      "make": "generic",
      "system": "powertrain",
      "subSystem": "Fuel and air metering",
      "number": "P0001",
      "description": "Fuel Volume Regulator Control Circuit/Open",
      "links": {
        "self": "https://diagnostic.vin.li/api/v1/codes/2db60bc5-0548-43ee-91c0-c34d59ce71ce"
      }
    }
  ],
}

"accel" : {
"min accel": nn,
"max accel": nn,
}

Verbiage states:
For each trip, more detailed information regarding overall trip statistics is available here. This includes start and stop location as well as a few other statistical information which may be of interest. These items include:

All of the detailed information listed in the above verbiage is available via the get trips by device or get trips by vehicle.

the request has a typo - "vehicle" should be "vehicles"
GET https://trips.vin.li/api/v1/vehicle/27b8db50-1274-11e4-9191-0800200c9a66/trips

Boundaries heading states ...boundaries can be either "parametric" or "geospatial." In the Rule document, the request/response examples only shows "parametric" but no "geospatial" examples. It would be good to show both.

Receiving Dates - first line last paragraph - ...will generally return URLs with Unit ... Unit should be "UNIX"

Delete a Subscription section's verbiage starts with a typo in Subscription:

Subscriptins are primarily...

Confusing when reading doc - count, totalCount, total are all used to mean "total" in the meta data. Please consider using just total instead.

Heading - Vehicle Service: first sentence:
... information regarding thee specifics about the vehicle. Thee should be the

The line reads: Enterprise-level applications, which require specific approval from Vinli, are able to manage a specific block of devices that are "owned" by the application. I don't see where the concept of a "block" of device IDs exists. If it does, I would expect that Device IDs being returned from a List all Devices request would be identified by their block, but there is no block attribute associated with a device or that pagination provides organization based on blocks for an enterprise application.

Under Request look for the "Since" bullet. ... If an since value is not... the indefinite article "a" should be used in lieu of "an" as "since" has a constant sound as the first character.

Rule Services overview file, Rules heading, In a nutshell 3rd bullet has an incomplete thought: ...For instance, if a device

Request is showing old style format and needs to be updated to show:
https://telemetry-dev.vin.li/api/v1/messages/{messageID}