TMC is an independent, primarily volunteer organization that relies on ad revenue to cover its operating costs. Please consider whitelisting TMC on your ad blocker or making a Paypal contribution here: paypal.me/SupportTMC

Model S REST API

Discussion in 'Model S: User Interface' started by timdorr, Feb 2, 2013.

  1. timdorr

    timdorr Model S P1698 / VIN 1657

    Joined:
    Aug 2, 2012
    Messages:
    449
    Location:
    Atlanta, Georgia, United States
    #1 timdorr, Feb 2, 2013
    Last edited: Nov 12, 2013
    I've created an Apiary.io page and Github repo for tracking the documentation of the API:

    http://docs.timdorr.apiary.io/
    https://github.com/timdorr/model-s-api

    I'd like some help with this. If you'd like to sniff the traffic of the Model S app, you can use Fiddler and your phone on your local wifi network using these instructions: Fiddler Web Debugger - Configuring Google Nexus 7 running Android 4.1 That will work for any Android 4.1 or higher device, with the exception of some manufacturers that have customized the interface very heavily. It may still be possible to install the Fiddler CA cert, but you'll have to figure that out on your own. Same goes for older versions of Android.

    I still need to list out the remaining API endpoints and document the return values. The syntax for Apiary is fairly simple, so if you can do Github Markdown, you can handle this system. Feel free to fork and submit pull requests and I'll merge in stuff whenever I can. The biggest thing missing is the authentication flow, which I don't know if that's OAuth or something else (it doesn't look OAuth, though).

    My hope is that we can build some cool apps out of this for our smartphones and for the web. For example, we could build a Windows Phone app (which is being worked on) or an Android widget. Or you could build web service to turn on the climate control at set times or after certain triggers. There are tons of possibilities here and I'm really excited to see what people can think up. REST means the API is easy to use and friendly, so there should be lots of us able to produce something against the API.

    Update 11/12/13:

    Sorry for going silent for a while. I'm going to try and document any new and hidden endpoints that are found, but I'd appreciate some help if you see any missing. The best option is to submit a pull request on Github. You can also PM me here, though I may take a while to respond.

    I'm also going to include a nice little HTTParty class for all you Rubyists out there that makes interacting with the API pretty simple. I'll throw that into the API repo on Github.
     
    • Like x 1
  2. PureAmps

    PureAmps Model S P85 (#2817)

    Joined:
    Oct 22, 2012
    Messages:
    354
    Location:
    SF Bay Area
    Tim, thanks for taking the initiative and setting this up. I'd be happy to contribute once the iOS app is available (of course, at the rate you are going you may be finished by then).

    In addition to Fiddler, another commonly used SSL proxy with auto-cert generation is mitmproxy (mitmproxy - home). Their documentation provides info on how to configure for iOS devices as well as Android.

    As far as authentication, was there an HTTP Authentication header sent with each request? Maybe they are just using cookies...

    I am really hoping for OAuth, as they could eventually extend the "My Tesla" page to support 3rd party web/mobile apps, without requiring the vehicle owner to give out their username/password. Maybe Tesla hasn't thought that far ahead yet...
     
  3. dmetcalf

    dmetcalf S258

    Joined:
    Jun 2, 2012
    Messages:
    131
    Location:
    Merritt Island, FL
    Thanks Tim. This is cool. Let me know by PM if you need some testers. I am letting some of my programming students have limited access to test Web apps so far and may let them go deeper if promising apps emerge.
     
  4. ahimberg

    ahimberg Member

    Joined:
    Aug 8, 2010
    Messages:
    347
    Location:
    Woodinville, WA
    The Auth is in form post format that sets cookies back on the client. I haven't monitored enough to know first login vs subsequent app launch is handled though -- what cookies their client is saving between sessions as its not resending user/pw each time.
     
  5. timdorr

    timdorr Model S P1698 / VIN 1657

    Joined:
    Aug 2, 2012
    Messages:
    449
    Location:
    Atlanta, Georgia, United States
    Updated the docs with the authentication flow. Looks like it needs both a _s_portal_session and user_credentials cookie set. I haven't seen if the _s_portal_session is completely necessary, but I'm guessing it will be.

    I also added some session logs to the github repo (hid my passwords, of course), if anyone wants to take a look. The root return is interesting because there's a telltale sign of a Rails app (the javascript is in an assets folder). I assume they're up to date on their Rails patches, but I'll make sure they're not susceptible to the YAML bug most recently. Definitely don't want people messing around with our cars or Tesla's systems!
     
  6. aviators99

    aviators99 Model S - R140

    Joined:
    Jan 1, 2010
    Messages:
    1,452
    Location:
    Weston, Florida, United States
    Cool. I now have a charge timer that I wrote in 5 minutes, using curl and cron.
     
  7. markwj

    markwj Moderator, Asia Pacific

    Joined:
    Apr 10, 2011
    Messages:
    3,655
    Location:
    Hong Kong
    I've been interested in the possible use of OVMS Apps to control multiple cars of different types - not necessarily just with OVMS modules. This allows us to extend the manufacturer's offering, and is real nice for those with more than one car in their garage. OVMS has received literally dozens of request for such support.

    GM/OnStar now have a published API (although are not permitting this to be used against real cars until late 2013).

    The Leaf carwings API has been reverse engineered.

    Now, you guys are reverse engineering the Tesla Model S RESTfull API.

    Perhaps the neatest way of doing this is by gatewaying at the server - no change to Apps necessary. But, I worry that the providers will rate limit requests from a single IP. Doing it at the server allows for all sorts of cool stuff (e.g.; timed pre-heat).

    We could also do this in the Apps themselves.

    But, my question is what is the legality of this? I suspect that it would be a contravention of the DMCA? I read that GM/OnStar stopped (or persuaded to stop) the VoltStats guy to stop - and he is now using a very restricted API just for him. What about Nissan? I guess the legalities of doing the reverse engineering vs using fruits of such work are different.

    Looking at the Model S API, it would be about an evening's work to do a server gateway. Scarily simple. I don't have the car (yet), but if someone (presumably an OVMS roadster owner who also has a Model S) wants to work with me on a proof-of-concept for this, I'm more than willing to give it a go.
     
  8. AnOutsider

    AnOutsider S532 # XS27

    Joined:
    Apr 3, 2009
    Messages:
    11,923
    Heh, makes you wonder why it's not in the app. Though, I guess it wouldn't be as reliable (app isn't running to send the commands or car isn't in reception)
     
  9. zax123

    zax123 CDN Model S P308

    Joined:
    Jun 4, 2012
    Messages:
    911
    Location:
    Candiac, QC, CAN
    Aviators,

    How did you do the auth part?
     
  10. Jason S

    Jason S Model S Sig Perf (P85)

    Joined:
    Apr 20, 2012
    Messages:
    1,350
    Location:
    Rocklin, CA
    Since charging starts when you plug it in, I imagine you'd have two parts --
    When you want it off -- every 5 minutes (15, w/e, just so you aren't spamming the auth) you tell it to start charging.
    When you want it on -- tell it to turn on and check once or twice later on the status.

    You'll hafta remember to turn off the cron job when away from home, or you make the script location aware if that's available via the API (I think it is).
     
  11. aviators99

    aviators99 Model S - R140

    Joined:
    Jan 1, 2010
    Messages:
    1,452
    Location:
    Weston, Florida, United States
    Well, I haven't actually tested it yet, but if you "stop charging" (either from the app/API or from the car), it won't start up again until it's told to "start charging". So you shouldn't need to do anything every 5 minutes.

    - - - Updated - - -

    I did it as described in the documentation linked in the OP. I made use of the '-c' and '--cookie' options for curl.
     
  12. Banahogg

    Banahogg Member

    Joined:
    Jan 22, 2013
    Messages:
    293
    Location:
    San Jose, CA
    I don't have my car yet to fully test, but using basic HTTP authentication (curl -u) can distinguish between correct and incorrect passwords and appears to correctly return an empty vehicle list for my account from that endpoint.
     
  13. widodh

    widodh Model S R231 EU

    Joined:
    Jan 23, 2011
    Messages:
    4,822
    Location:
    Middelburg, The Netherlands
    Why? We are just doing HTTP requests to the Tesla servers.

    They are just the same requests as the App would do. What is not legal about doing those HTTP requests as long as you are not hammering the servers?

    Maybe reverse-engineering is forbidden in the US, but is it reverse engineering? You are just looking at the HTTP traffic your phone is doing.

    If Tesla would sue somebody I'd be angry at them, then they are showing that they aren't different at all. Then they would be whining about nothing. I just see cool potential for customers to control their car in cool ways.

    Log data about the location, energy usage, etc, etc. Super cool stuff! They should even help us with this and give hints. Even better, place the API documentation online at something like "developers.teslamotors.com"
     
  14. aviators99

    aviators99 Model S - R140

    Joined:
    Jan 1, 2010
    Messages:
    1,452
    Location:
    Weston, Florida, United States
    Are you talking about using basic authentication to the /vehicles URI or /login? /login doesn't return a vehicles list.
     
  15. brianman

    brianman Burrito Founder

    Joined:
    Nov 10, 2011
    Messages:
    15,487
    IMO, technically it is reverse engineering. I doubt Tesla will have issue with this particular flavor of it though. Disassembling your car physically and/or electrically is more what they're worried about in the legal sense, I think.
     
  16. PureAmps

    PureAmps Model S P85 (#2817)

    Joined:
    Oct 22, 2012
    Messages:
    354
    Location:
    SF Bay Area
    A quick note on using the API. The id to use when issuing vehicle commands is the "id" field from the vehicles JSON response, not the "vehicle_id" field. It took me a bit to figure that out, since I haven't been able to record any traffic from the actual app, it wasn't obvious what the problem was. I have everything working now. :)
     
  17. Banahogg

    Banahogg Member

    Joined:
    Jan 22, 2013
    Messages:
    293
    Location:
    San Jose, CA
    I was accessing the vehicles URL.
     
  18. gg_got_a_tesla

    gg_got_a_tesla Model S: VIN P65513, Model 3 Res Holder

    Joined:
    Jan 29, 2010
    Messages:
    6,097
    Location:
    Redwood Shores, CA
    Would it be a good idea to put together a simple .war or equivalent with a web frontend? We could distribute the war around here and folks can deploy in a container on their home machines if not host it publicly. My UI/UX skills are rusty but, I'll work on this too.
     
  19. patp

    patp Member

    Joined:
    Aug 2, 2010
    Messages:
    514
    Location:
    Canada
    Very cool. Would you mind posting your script - this would save me some time. Thanks!
     
  20. PureAmps

    PureAmps Model S P85 (#2817)

    Joined:
    Oct 22, 2012
    Messages:
    354
    Location:
    SF Bay Area
    I agree, I don't think Tesla is that concerned about reverse engineering their mobile app's API. The legal issue here is not so much about reverse engineering, but Tesla's terms of service for their web app that is supporting the mobile apps. I don't have the mobile app yet, so I don't know if there is an accompanying "click wrap" license. But if they state that the API may only be accessed via their application, then you would be in violation of their terms of use. They have a simple remedy, which would be to just disable your account.

    Until I hear otherwise, I'm treating this as an "ask forgiveness" opportunity. :) But I hope anyone using the API would be careful to not create headaches for Tesla (for example too many API requests, etc.) that could quickly bring this little "experiment" to an end.
     

Share This Page