
Unofficial documentation of the Tesla Model S REST API - timdorr
https://github.com/timdorr/model-s-api
======
timdorr
Docs are here: <http://docs.timdorr.apiary.io/>

This was discovered via the Android app in particular:
[https://play.google.com/store/apps/details?id=com.teslamotor...](https://play.google.com/store/apps/details?id=com.teslamotors.tesla)

I did some sniffing on the traffic, which is SSL encrypted, but luckily it's
pretty easy to install your own CA in Android 4.1+.

They have both a Rails app and a nodejs server. The nodejs server is for live
streaming car location and driving metrics. I haven't gotten that documented
yet (but I'm accepting pull requests!), but some people have already been
making use of it:
[http://www.teslamotorsclub.com/showthread.php/13410-Model-S-...](http://www.teslamotorsclub.com/showthread.php/13410-Model-
S-REST-API)

One guy already has his Model S tweeting: <https://twitter.com/pureamps>

~~~
owenfi
I _love_ Tesla, and the Model S seems great, but having a rails app server on
my luxury car seems capricious.

How does it get updated? An attacker can _at least_ unlock the doors or drain
the battery (lights & HVAC control), and possibly it is an entry point for
something much worse (unlocking & starting, or disabling controls while
enroute). Is this a major security flaw or am I just spreading FUD?

~~~
revelation
It doesn't have a rails server on the car. The car communicates to Teslas
datacenter, which is where the Rails servers are. You then query the API by
querying the datacenter.

~~~
mrmaddog
I certainly hope the engineers their are staying on top of the recent deluge
of Rails patches. Tesla's database has a huge amount of private data; mostly
containing information about rich and influential people. A black hat could
undoubtedly profit by tracking people and correlating their location to
affairs/secret business meetings/etc.

~~~
mratzloff
According to Elon Musk, it only sends data if you explicitly enable it.

~~~
ibrahima
I'd just like to add that they enabled it by default for cars they lend to
media outlets for reviews after the Top Gun thing. Some people in the other
thread were freaking out about how much Tesla knows about your car but a
regular customer can just opt out.

~~~
ChrisCooper
I think you meant "Top Gear". ;)

------
dochtman
Using GET to trigger horn honking... Not sure I'd consider that good REST
practices.

(At least honking the horn doesn't incur permanent state change; unlocking the
doors is obviously not safe.)

Edit: idempotency vs safety... I knew I was being stupid.

~~~
parfe
Unlocking doors absolutely is idempotent. What different state would you see
if you issue Unlock once or a thousand times?

~~~
jws
Solenoid melted?

~~~
joezydeco
Thinking like an embedded systems engineer (I am) instead of a mathematician
(I'm not), I would have a sensor to know the state of the lock and only whack
the unlock solenoid if the lock has been discovered to be closed.

Always treat mechanical devices in a non-deterministic fashion.

~~~
DoubleCluster
As a software developer I'd always try to unlock it. The user probably has a
reason for pressing the button. Maybe your "is the door locked" sensor is
broken? If you're afraid of overheating it wait a bit after the second try
before enabling it again.

~~~
jrabone
You might be surprised by the semantics assigned to double clicking the button
by some manufacturers. On some BMWs (mine included) locking it twice DISABLES
the alarm. It's intended for ferries / low-loader recovery etc. but if you
don't know it...

~~~
arethuza
VWs can do a thing where the windows open if you hold the lock key down -
fortunately this can be turned off in the cars configuration settings for
people who live in rainy countries!

~~~
dbaupp
Just to be precise, the windows open when holding the unlock button, and close
when holding the lock button.

------
beaumartinez
Does Tesla describe it as a _RESTful API_ , though? By the looks of things,
the author has discovered it and decided to call it RESTful himself, even
though it's just an HTTP API.

A RESTful API is more than just using GET to access resources.

~~~
sopooneo
I agree. This interface is not RESTful, and that's good, because it's not a
good fit for REST. I may be wrong, but it seems REST is best suited for
accessing and creating _resources_. And it seems you would have to do a lot of
conceptual mashing to represent all this API needs to do as resources. I am
happy to be corrected.

~~~
bct
What "conceptual mashing" is required? Your resources are things like locks,
batteries and thermostats. It seems pretty straightforward to me.

~~~
sopooneo
You may have a point that I didn't consider. So if we wanted to unlock the
car, would we perhaps post new a version of the lock resource (in json, xml,
or whatever serialization format the system uses), representing its new state,
to the uri representing it?

Exampe: POST {"state": "unlocked} to <http://doors/front-left/lock>

I realize I don't understand this, so your comment, and any further points you
have, are sincerely appreciated.

~~~
bct
Exactly. (except you would probably want to PUT the state instead of POST,
since it's an idempotent operation)

You would GET the lock to see if it's locked, GET the battery to read its
charging state.

You could PUT to the battery (or to some more abstract, finer-grained
resources) to set the charge mode and turn charging on and off. The HVAC and
thermostat would work the same way.

The only tricky stuff is "flash lights" and "honk horn"; they're inherently
commands, so you might as well implement them in the RPC style that Tesla has
used. They can't benefit from anything REST has to offer anyways.

~~~
sopooneo
Thank you. That is very helpful. But what about if it was necessary to have
one command that changed the state of more than one resource?

And as you say, since certain aspects of the API (like honk horn) are unfit
for REST, does it make sense to have the other parts of the API in REST? And
then you've have two API's at once?

~~~
bct
> But what about if it was necessary to have one command that changed the
> state of more than one resource?

Then you need to have another resource that encompasses the aspects that need
to be changed. Sometimes resources have to be somewhat abstract.

> since certain aspects of the API (like honk horn) are unfit for REST, does
> it make sense to have the other parts of the API in REST?

If the application benefits from the constraints that REST provides then why
wouldn't it make sense? It's still one API, "honk" and "flash" don't need to
be walled off from the other elements of the API in any way.

------
mixedbit
Hope this is secured against cross car request forgery.

~~~
driverdan
My first thought was "Holy Shit! Cookie only authentication and you can unlock
the doors, among other things!"

It's absolutely vulnerable to XSRF with cookie only authentication. This is a
huge security issue.

------
nathan_long
What I would like to see is USB plug in every car, which provides diagnostic
and maintenance data according to a standardized format. This should be
available to the owner and to any shop they authorize to work on the car.

~~~
drzaiusapelord
The OBD2 standard does this today. Not pretty, but works well enough. I always
check my fault codes before going to the mechanic.

>which provides diagnostic and maintenance data according to a standardized
format.

Except the values you get won't make any sense outside of your particular
model. Its like reading SMART data from a hard drive. Okay, you can generate
this csv and have all this data, but without the manufacturer telling what
thresholds matter (and these are arguable), its kinda meaningless. SMART was
supposed to predict failures and do all sorts of things, but its kind useless
in practice. I think most controllers just stupidly rely on bad blocks
appearing than trying to interpret the tea leaves of SMART data.

With OBD systems, all this information is internal and we get a fault code
when we pass a certain threshold. I think this makes it a lot easier for
mechanics and lay people to work with. Data addicts, of course, will never be
satisfied unless they can pull every bit out of the system, but that may not
be practical or useful. I could see a hybrid system where a car has the old
fashioned OBD2 protocol and something else for nerds to download.

~~~
moron4hire
Getting at that level of data would be possible if you could access the CAN
bus. It's part of the OBD-II standard, but most manufacturers don't forward
the CAN bus data to that specific connector hidden under your steering column.
However, _a few_ do, and there are other connections in other locations for
the other makes.

~~~
emidln
You can access the CAN bus pretty cheaply (there are several cards available
around $200 with linux drivers, maybe cheaper if you're willing to do more
than plug it in and turn on wireshark). That said, the last time I worked on
ECMs, the messages were not standardized at all. You needed a spec to define
what variations of ECMs were available as well as what the individual values
would mean. I feel like GM was standardizing this more than others in an
effort to consolidate ECMs they were shipping (runtime config via
"calibrations" I believe), and all manufacturers might be using standardized
parts now, but you'll still need to know not only the message inventory for
your vehicle, but you'll want to know whatever diagnostic protocol that your
manufacturer uses to sit on top of CAN. Keyword Protocol 2000 was used by
DaimlerChrysler was used when I was still in the business and GMLAN was used
by GM for these purposes.

~~~
stevenrace
The Goodthopter [1], an offshoot of Travis Goodspeed's 'GoodFET' project,
allows CAN access for about $35 all in. It's basically a MSP430 + a CAN
controller.

Even 'simple' CAN protocols, like J1939 used in trucks/agri/marine, are
purposely non-standard. It's rather annoying.

I'm curious as to what systems will emerge from Mercedes/VW/BMW (and I guess
Google) as more high speed sources like LiDAR, active dampening, etc become
the norm. The current BMW 5/7 series and Mercedes' S-class already have
separate CAN-like systems for high speed buses.

[1] <http://goodfet.sourceforge.net/hardware/goodthopter11/>

------
ge0rg
Wow, finally a way for us nerds to interact with our cars, besides of hunting
undocumented CAN bus commands via OBD2!

~~~
rescovi
Would also be nice if we had publicicly available IVI computers with proper
car APIs to tinker and play with. Any ideas if there are other available than
upcoming Tizen IVI reference hardware (which is not yet available for 2.0
afaik)?

------
nolok
It has an active 3G connection at all times and can be queried for its GPS
position ? Damn, future is both exciting (tech wise) and scary (privacy wise).

Now that I think about it I'm sure it's not the only car with this, but I
didn't realize before

~~~
mlnowak
This is really actively used in fleet management domain today. Mostly for
utilization analytics, fuel usage, idling detection, driver behavior etc. It
is amazing how many efficiencies can be found in the data...

------
spoonyg
I use this every night from a python script to force the charge to start after
the electricity becomes cheaper. So far it is fast and reliable.

------
onethumb
Neat! Couple of nits, though, if anyone from Tesla is reading:

\- Wish it used OAuth or some other revocable token mechanism. What if I lose
my device? Sell the car? Get a divorce? etc..

\- GET for things that change state? Looks like these are all idempotent, so
they should be PUT.

\- Versioning might be nice. :)

Still, progress! Clean API over HTTP that returns easy-to-parse JSON _for a
car_ = win.

------
MatthewPhillips
Coming soon to the HN front page: RoadRage.js

------
stereo
This would make an interesting music instrument. I hope someone writes
something that makes it MIDI-compatible.

------
alexjeffrey
I hate to think what would happen if tesla's user database was hacked. Not
that that's a reason not to have a REST API of course, I hope to see a lot of
car-app innovation come from this!

------
ekurutepe
Do the cars have an onboard wifi for the server-client communication? Is this
API also open to the Internet over the car's cellular connection? (if there is
one of course)

~~~
timdorr
It's over 3G for now. There is wifi hardware in the car, but they haven't
built out an interface for it yet.

All Model S's come with 3 months of cell service and they will be offering
data plans shortly. It's running on AT&T, so we should be able to add it to
Mobile Share plans (which I plan to do).

~~~
toomuchtodo
Is the SIM soldered? Or can you drop a T-Mobile SIM card in?

/T-Mobile user

~~~
sahaskatta
I looked around and didn't see a SIM slot. Tesla hasn't disclosed the carrier
in use either.

They did however say that you'll be able to tether a phone with a data
connection to the car via USB to avoid paying a subscription for the car.

~~~
toomuchtodo
I don't mind paying the subscription; I just hate AT&T with the passion of ten
fiery hells.

------
xetorthio
It is weird that you connect to the API through http and send user and
password in plain text.

~~~
timdorr
It's https, actually.

------
raphaelj
[http://www.youtube.com/watch?feature=player_detailpage&v...](http://www.youtube.com/watch?feature=player_detailpage&v=meY1R43fJIQ#t=35s)

------
pjmlp
Lovely

/vehicles/{id}/command/door_unlock

~~~
calinet6
Exactly what I was thinking... one vulnerability in their stack and every car
is pwned.

~~~
emidln
Meh, you've had these for years. I'd put it at even money that some RF
protocol stacks on recent vehicles are vulnerable to exploitation and
connected to one of the CAN buses on the vehicle so you can pivot to a more
critical system. Hurray for drive by exploits (literally).

I'm honestly surprised that criminal organizations haven't paid/coerced
engineers working how to steal certain cars using a remote control, because
I'm pretty certain that with some effort, it's possible.

------
driverdan
Hello XSRF! Cookie only authentication? Seriously?

~~~
timdorr
This is only accessed directly via library, so CSRF isn't a factor. Also,
everything is happening over SSL.

~~~
mikeash
SSL wouldn't save you, but if you never get the magic cookie into a browser
then you're safe from XSRF.

------
miket
This is great! Can't wait until they add steering, gas, and brake to the API.

------
dwiamo
Not a new thing - Tesla not the first automotive to do this.

------
coldskull
wow....they are using GETs for everything ! :)

