-
Notifications
You must be signed in to change notification settings - Fork 1
WebSocket API
- id - the unique id for a vehicle, is an integer
- clusterId - the path of the cluster containing the vehicle
- latitude/longitude - floats indicating the gps position of the vehicle
- metadata - a json object used to store information
- status - indicates the status of the vehicle
- "Offline" - vehicle is not being routed, is the default status
- "Online" - vehicle can be routed
- id - the unique id for the commodity
- clusterId - the path of the cluster containing the commodity
- startLatitude/startLongitude - floats indicating the position the commodity is being picked up from
- endLatitude/endLongitude - floats indicating the position the commodity is to be dropped off at
- metadata - a json object used to store information
- status - indicates the status of the commodity
- Inactive - commodity is to be ignored by the router, is the default status
- Waiting - commodity is waiting for a vehicle, it should be routed
- PickedUp - commodity is traveling in a vehicle
- DroppedOff - commodity was dropped off at its destination
- Cancelled - commodity was cancelled and should be ignored by the router
In order to read a vehicle, you use read, specifying the vehicle model and its id. The reponse stores the requested vehicle in the value field, here is how to read the vehicle from a socket
var vehicle;
socket.onmessage = function(msg){
var resp = msg.data;
vehicle = resp.model.value;
};
var msg = {
"message":"Read",
"model":"Vehicle",
"id":4
};
socket.send(Json.stringify(msg));
For the request, you specify the Vehicle type and provide the id of the desired Vehicle
{
"message":"Read",
"model":"Vehicle",
"id":4
}
The response has a model object that contains the vehicle as the value
{
"message":"Model",
"model":"Vehicle",
"value":{
"id":4,
"longitude":2,
"latitude":7,
"status":"Online",
"metadata":{"capacity":6},
"commodities":[]
}
}
A new vehicle requires a latitude, longitude, capacity, and clusterId
{
"message":"Create",
"model":"Vehicle",
"value":{
"latitude":0.123,
"longitude":0.456,
"metadata":{"capacity":4},
"status":"Online",
"clusterId":"appcluster/subcluster"
}
}
The response is an object with created which has the vehicle as the value
{
"message":"Created",
"model":"Vehicle",
"value":{
"id":20,
"latitude":0.123,
"longitude":0.456,
"status":"Online",
"metadata":{"capacity":4},
"commodities":[]
}
}
An update is similar to a create except you need so specify the id of the row that you are updating, for an update, no fields are required for a vehicle.
{
"message":"Update",
"model":"Vehicle",
"id":6,
"value":{
"latitude":1.2,
"longitude":66,
"metadata":{"capacity":10,"email":"[email protected]"}
}
}
{
"message":"Updated",
"model":"Vehicle",
"value":{
"id":6,
"latitude":0.123,
"longitude":0.456,
"status":"Online",
"metadata":{"capacity":10,"email":"[email protected]"},
"commodities":[]
}
}
{
"message":"Delete",
"model":"Vehicle",
"id":4
}
{
"message":"Deleted",
"model":"Vehicle",
"value":{
"id":4,
"latitude":40,
"longitude":30,
"status":"Offline",
"metadata":{"capacity":11},
"commodities":[]
}
}
Reading Commodities is similar to reading vehicles, you just use Commodity instead of Vehicle for the type field
{
"message":"Read",
"model":"Commodity",
"id":4
}
The response has a model object that contains the commodity
{
"message":"Model",
"model":"Commodity",
"value":{
"id":4,
"longitude":2,
"latitude":7,
"status":"PickedUp",
"metadata":{"param":6},
"vehicleId":6
}
}
A new commodity requires a startLatitude, startLongitude, endLatitude, endLongitude, a param, and a clusterId
{
"message":"Create",
"model":"Commodity",
"value":{
"startLatitude":0.123,
"startLongitude":0.456,
"endLatitude":0.789,
"endLongitude":0.101
"metadata":{"param":4},
"status":"Waiting",
"clusterId":"cluster/subcluster"
}
}
The response is an object with created which has the Commodity
{
"message":"Created",
"model":"Commodity",
"value":{
"id":20,
"startLatitude":0.123,
"startLongitude":0.456,
"endLatitude":0.789,
"endLongitude":0.101,
"status":"Waiting",
"metadata":{"param":4}
}
}
An update is similar to a create except you need so specify the id of the row that you are updating, for an update, no fields are required for a commodity.
{
"message":"Update",
"model":"Commodity",
"id":6,
"value":{
"endLatitude":1.2,
"endLongitude":66,
"status":"DroppedOff"
}
}
{
"message":"Updated",
"model":"Vehicle",
"value":{
"id":6
"startLatitude":0.123,
"startLongitude":0.456,
"endLatitude":1.2,
"endLongitude":66,
"status":"DroppedOff",
"metadata":{"param":4},
"commodities":[]
}
}
Like a vehicle, you delete the commodity by specifying its id
{
"message":"Delete",
"model":"Commodity",
"id":4
}
{
"message":"Deleted",
"model":"Commodity",
"value":{
"id":6,
"startLatitude":0.123,
"startLongitude":0.456,
"endLatitude":1.2,
"endLongitude":66,
"status":"Cancelled",
"metadata":{"param":4}
}
}
Clusters can read, created and deleted
{
"message":"Read",
"model":"Cluster",
"id":"APP-CLUSTER/cluster"
}
{
"message":"Model"
"model":"Cluster",
"value":{
"id": "cluster",
"vehicles":[
{ "id": 1, "latitude":19, "longitude":77, "metadata":{"capacity":3}, "status":"Offline", "commodities":[] },
{ "id": 2, "latitude":10, "longitude":22, "metadata":{"capacity":4}, "status":"Offline", "commodities":[] },
{ "id": 3, "latitude":21, "longitude":31, "metadata":{"capacity":2}, "status":"Offline", "commodities":[] }
],
"commodities":[
{ "id":6, "metadata":{"param":4},
"startLatitude":0.123, "startLongitude":0.456,
"endLatitude":1.2, "endLongitude":66,
"status":"Inactive" },
{ "id":8, "metadata":{"param":3},
"startLatitude":923, "startLongitude":5.756,
"endLatitude":77, "endLongitude":606,
"status":"Inactive" }
],
"subClusters":[]
}
}
clusters can be created with a path
{
"message":"Create",
"model":"Cluster",
"value":{ "id":"app-id" }
}
{
"message":"Created",
"model":"Cluster",
"value":{
"id":10,
"commodities":[],
"vehicles":[],
"subClusters":[]
}
}
A subcluster is created by placing the parent id in front of the subCluster name separated by a slash
{
"message":"Create",
"model":"Cluster",
"value":{ "id":"api-id/subCluster" }
}
Deleting a cluster is similar to deleting a commodity or a vehicle
{
"message":"Delete",
"model":"Cluster",
"id":"cluster"
}
{
"message":"Deleted",
"model":"Cluster",
"value":{
"id": "cluster",
"parent":8,
"vehicles":[
{ "id": 1, "latitude":19, "longitude":77, "metadata":{"capacity":3}, "status":"Offline", "commodities":[] },
{ "id": 2, "latitude":10, "longitude":22, "metadata":{"capacity":4}, "status":"Online", "commodities":[] },
{ "id": 3, "latitude":21, "longitude":31, "metadata":{"capacity":2}, "status":"Offline", "commodities":[] }
],
"commodities":[
{ "id":6, "metadata":{"param":4},
"startLatitude":0.123, "startLongitude":0.456,
"endLatitude":1.2, "endLongitude":66,
"status":"Waiting" },
{ "id":8, "metadata":{"param":3},
"startLatitude":923, "startLongitude":5.756,
"endLatitude":77, "endLongitude":606,
"status":"DroppedOff" }
],
"subclusters":[]
}
}
The user can obtain a route for any vehicle or commodity
The route request requires the model type and its id
{
"message":"Route",
"model":"Vehicle",
"id":78
}
The route contains an array of actions which each have a position and a commodity, note that if a Route request is made for a cluster, the route value is an array of all the routes in the cluster.
{
"message":"Routed",
"model":"Vehicle"
"value":{"id":78, "latitude":100, "longitude":-150, "metadata":{capacity":3}, "status":"Online", "commodities":[]},
"route":{
"Vehicle":{"id":78, "latitude":100, "longitude":-150, "metadata":{"capacity":3}, "status":"Online"},
"actions":[
{ "action":"Start","latitude":100,"longitude":-150 },
{ "action":"PickUp","latitude":20,"longitude":5,
"commodity":{ "id":20, "startLatitude":20, "startLongitude":5, "endLatitude":5, "endLongitude":12, "metadata":{"param":3}, "status":"Waiting" },
{ "action":"PickUp","latitude":12,"longitude":20,"commodity":{ "id":21, \\ other commodity fields } },
{ "action":"DropOff","latitude":2,"longitude":30,"commodity":{ "id":21, \\ other commodity fields } },
{ "action":"DropOff","latitude":5,"longitude":12,"commodity":{ "id":20, \\ other commodity fields } }
]
}
}
{
"message":"Routed",
"model":"Cluster",
"value":{
"id":"ClusterPath",
"vehicles":[
{"id":78,"latitude":100, "longitude":-150, "metadata":{"capacity":3}, "status":"Online", "commodities":[] },
{"id":10,"latitude":90, "longitude":-160, "metadata":{"capacity":2}, "status":"Online", "commodities":[] }
],
"commodities":[
{ "id":20, "startLatitude":20, "startLongitude":5, "endLatitude":5, "endLongitude":12, "metadata":{"param":3}, "status":"Waiting" },
{ "id":21, ... },
{ "id":30, ... }
],
"subClusters":[
{ "id":"ClusterPath/subCluster", "vehicles":[], "commodities":[], "subClusters":[] }
]
},
"route":[
{
"Vehicle":{"id":78, "latitude":100, "longitude":-150, "metadata":{"capacity":3}, "status":"Online", "commodities":[] },
"actions":[
{ "action":"Start","latitude":100,"longitude":-150 },
{ "action":"PickUp","latitude":20,"longitude":5,
"commodity":{ "id":20, "startLatitude":20, "startLongitude":5, "endLatitude":5, "endLongitude":12, "metadata":{"param":3}, "status":"Waiting" },
{ "action":"PickUp","latitude":12,"longitude":20,"commodity":{ "id":21, /* other commodity fields */} },
{ "action":"DropOff","latitude":2,"longitude":30,"commodity":{ "id":21, /* other commodity fields */} },
{ "action":"DropOff","latitude":5,"longitude":12,"commodity":{ "id":20, /* other commodity fields */} }
]
},{
"vehicle":{"id":10,"latitude":90, "longitude":-160, "metadata":{"capacity":2}, "status":"Online"},
"actions":[
{ "action":"Start", "latitude":90, "longitude":-160, "commodity":{ "id":30, ... }},
{ "action":"PickUp", "latitude":89, "longitude":-150, "commodity":{ "id":12, ... }}
]
}
]
}
You may want to subscribe to clusters or to models so that you are notified of relevant changes. This can be done through subscriptions. When subscribing to a model, you receive Updated messages for whenever it is changed, or a Deleted message when it is deleted. You can also subscribe to clusters to receive notifications on the vehicles or commodities in it
Here is how to get notifications for whenever a vehicle is changed in a cluster, you can do the same for commodities too.
{
"message":"Subscribe",
"model":"Vehicle",
"clusterId":"clusterPath"
}
{
"message":"Subscribed",
"model":"Vehicle",
"clusterId":"clusterPath"
}
You now will receive either a Created, Updated or Deleted message whenever a vehicle is created, updated, or deleted in the cluster
Sometimes you may want to subscribe to a specific vehicle or commodity, such as if you want to receive a vehicle's position in real time. A model level subscription request is similar to a cluster level subscription request.
{
"message":"Subscribe",
"model":"Vehicle",
"id":6
}
{
"message":"Subscribed",
"model":"Vehicle",
"id":6
}
You now will receive Update messages whenever the vehicle is modified
Route subscriptions are similar to subscriptions except you receive the subscribed route whenever it changes. You can subscribe to the routes for vehicles, commodities, and clusters. After subscribing, the socket will receive Routed messages whenever the subscribed route changes. Note that after subscribing, the socket is immediately sent the most up to date route even if it has not changed since subscribing.
{
"message":"RouteSubscribe",
"model":"Vehicle",
"id":10
}
{
"message":"RouteSubscribed",
"model":"Vehicle",
"id":10
}
{
"message":"GetApplicationCluster",
"id":"9c4166bb-9535-49e1-8844-1904a0b1f45b"
}
{
"message":"ApplicationCluster",
"id":"9c4166bb-9535-49e1-8844-1904a0b1f45b",
"clusterId":10
}