You can try this yourself using
http://tmc.openvehicles.com/api. At the moment I've only enabled HTTP. I'll enable HTTPS (the server already supports it - I just need to install the certificates) when we are ready for production.
The first thing you must do to use the api is authenticate to establish a session and get a cookie (so you don't need to authenticate every time). This is done with a http "GET /api/cookie" passing parameters 'username' and 'password' as your
www.openvehicles.com username and password respectively.
$ curl -v -X GET -c cookiejar http://tmc.openvehicles.com:6868/api/cookie?username=USERNAME\&password=PASSWORD
* About to connect() to tmc.openvehicles.com port 6868 (#0)
* Trying 64.111.70.40...
* connected
* Connected to tmc.openvehicles.com (64.111.70.40) port 6868 (#0)
> GET /api/cookie?username=USERNAME&password=PASSWORD HTTP/1.1
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: tmc.openvehicles.com:6868
> Accept: */*
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 Authentication ok
< Connection: close
< Content-Length: 9
< Cache-Control: max-age=0
< Content-Type: text/plain
* Added cookie ovmsapisession="9ed66d0e-5768-414e-b06d-476f13be40ff" for domain tmc.openvehicles.com, path /api/, expire 0
< Set-Cookie: ovmsapisession=9ed66d0e-5768-414e-b06d-476f13be40ff
< Date: Fri, 22 Feb 2013 12:43:56 GMT
< Expires: Fri, 22 Feb 2013 12:43:56 GMT
<
Login ok
Once logged in, all subsequent requests should pass the cookie (ovmsapisession). The session will expire after 3 minutes of no use, or you can specifically terminate / logout the session by calling "DELETE /api/cookie".
We could have other authentication mechanisms, but I'm really trying to move to a simple username/password mechanism.
To obtain a list of vehicles on your account, you can use the "GET /api/vehicles" call:
$ curl -v -X GET -b cookiejar http://tmc.openvehicles.com:6868/api/vehicles
* About to connect() to tmc.openvehicles.com port 6868 (#0)
* Trying 64.111.70.40...
* connected
* Connected to tmc.openvehicles.com (64.111.70.40) port 6868 (#0)
> GET /api/vehicles HTTP/1.1
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: tmc.openvehicles.com:6868
> Accept: */*
> Cookie: ovmsapisession=9ed66d0e-5768-414e-b06d-476f13be40ff
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 Logout ok
< Connection: close
< Content-Length: 280
< Cache-Control: max-age=0
< Content-Type: application/json
< Date: Fri, 22 Feb 2013 12:44:41 GMT
< Expires: Fri, 22 Feb 2013 12:44:41 GMT
<
[ {"id":"DEMO","v_apps_connected":0,"v_net_connected":1},
{"id":"MARKSCAR","v_apps_connected":1,"v_net_connected":1},
{"id":"QCCAR","v_apps_connected":0,"v_net_connected":0},
{"id":"RALLYCAR","v_apps_connected":0,"v_net_connected":0},
{"id":"TESTCAR","v_apps_connected":0,"v_net_connected":0}
]
(note that the above is re-formatted slightly, to make it clearer to read).
The return data is a json formatted array of hashes. Each record is one for one vehicle and shows you the vehicle id, as well as counts for the number of apps currently connected to that vehicle, and whether the vehicle is connected to the net (server) or not.
From the server point of view, we can treat an api session just like an app session. From the vehicle point of view there will be no difference - once an API connects to a vehicle, the server will send a "Z 1" message to tell the module it has a connection. If the session times out or is logged out, the server will inform the modules in the vehicles.
The above has all been implemented, and you can try it.
The following commands are what I am thinking about:
GET /api/protocol/<VEHICLEID> Return raw protocol records (no vehicle connection)
GET /api/vehicle/<VEHICLEID> Connect to, and return vehicle information
DELETE /api/vehicle/<VEHICLEID> Disconnect from vehicle
GET /api/status/<VEHICLEID> Return vehicle status
GET /api/tpms/<VEHICLEID> Return toms status
GET /api/location/<VEHICLEID> Return vehicle location
GET /api/charge/<VEHICLEID> Return vehicle charge status
PUT /api/charge/<VEHICLEID> Set vehicle charge status
DELETE /api/charge/<VEHICLEID> Abort a vehicle charge
GET /api/lock/<VEHICLEID> Return vehicle lock status
PUT /api/lock/<VEHICLEID> Lock a vehicle
DELETE /api/lock/<VEHICLEID> Unlock a vehicle
GET /api/valet/<VEHICLEID> Return valet status
PUT /api/valet/<VEHICLEID> Enable valet mode
DELETE /api/valet/<VEHICLEID> Disable valet mode
GET /api/features/<VEHICLEID> Return vehicle features
PUT /api/feature/<VEHICLEID> Set a vehicle feature
GET /api/parameters/<VEHICLEID> Return vehicle parameters
PUT /api/parameter/<VEHICLEID> Set a vehicle parameter
PUT /api/reset/<VEHICLEID> Reset the module in a particular vehicle
PUT /api/homelink/<VEHICLEID> Activate home link