5 ms·

> This is unofficial documentation of the Tesla Model S REST API Very few concepts have been so hugely corrupted to mean exactly the opposite of what they mean

by dlisboa 12y ago

> This is unofficial documentation of the Tesla Model S REST API Very few concepts have been so hugely corrupted to mean exactly the opposite of what they mean as REST. This is probably the least REST API in existence.

gregory144 12y ago
I agree with you, but I have trouble understanding the right way to implement "commands" like this - I must be thinking about it in the wrong way. How would you design a "real" REST interface for a command like this? What's the advantage a "real" REST interface gives you in this case?
- benregenspan 12y ago
  Exactly -- where does something that is designed for "state transfer" get you when the goal is to only temporarily modify a state/send a command that modifies internal state for X amount of time, not really "transfer" one at all? REST maps very nicely to CRUD operations, but not to this.
  - zachrose 12y ago
    Sure, but maybe you could think of POSTing to /honks as "creating a honk." This would make sense if you wanted to GET /honks and see a collection of previous honks. (Modifying an existing honk doesn't make sense, so we wouldn't have to worry about it.)
    - andrewstuart2 12y ago
      I wouldn't mind performing GET /vehicle/{id}/honks?since={time}&limit=1000 to see an indicator of how aggressively my car has been driven. Especially if somebody else is driving it.
    - shawnz 12y ago
      I think this interpretation is the best fit. Similarly PUT would be appropriate for requests where you are specifying the time that the honk should occur, which would make them idempotent.
- benregenspan 12y ago
  (That said, they should definitely use POST here!)
- jholman 12y ago
  Right. REST is about Transfering the State's REpresentation. In this case, we want to transfer an event ("honk!"). You could argue that we want to transfer a state transition ("begin honking"), and let some other process (the car) handle the next transition ("cease honking") independently, but that's forced, and in any case it's not RESTful either. As far as I can tell, REST is appropriate in very few cases.... although it IS appropriate for more cases than it might first appear.
- chrisrogers 12y ago
  You would use RPC.
  - icambron 12y ago
    This. While this API is not RESTful at all, that's just a nomenclature problem; it's totally fine as an API [1]. RPC is perfectly appropriate for a wide range of problems and there's no need to shoehorn every application into REST just because people say It's the Thing to Do. I could imagine a RESTful API for this, as people have above, and it might work well. But it isn't some sort of obvious best practice. [1] Except that it really ought to use POST.
- andrewstuart2 12y ago
  I don't know the whole state of the vehicle. I don't want to. So I'll use PATCH. I know I want the horn to be in a honking state and remain in that state for 1 second. The implementation is responsible for doing what it needs to do in order to get the resource into the state (or differential state in this case) I told it to take. I'm not usually in favor of nested API design, but complex resources like cars make sense, so: PATCH /vehicles/{id}/horn { "enabled": true, "timeRemaining": 1000 }
  - SilasX 12y ago
    My initial thought would be that a request for a "honk action" is not idempotent, so it should be a POST. You could do it as a PUT or PATCH, but you'd have to do it differently from in your example in order to preserve idempotence, due to the complications of working with time. Remember, if the request successfully goes through twice that should have the same effect as if only the first succeeded. One way to accomplish that would be to give an absolute start and end time for honk to be on. e.g., PUT /vehicles/{id}/horn { "enabled": true, "time_start": "2014-04-12T20:12:36.1", "time_end": "2014-04-12T20:12:36.6"} for a half-second honk.
- dlisboa 12y ago
  There are some ways, I'm just thinking off the top of my head for one here. If the resources of the car were mapped and had states it could work fine with a full REST interface. You could change the state of the horn like you change the state of a switch. You'd change the horn to be "on", not call some "turn it on" procedure. They have some indications of that. There's a URL that returns the state of the vehicle (driving and position). That's something that could be mapped as a first-class citizen and someone could mess with it with the semantics of the verbs. Commands are a much more RPC area though, REST doesn't map perfectly. You can almost always make a command into something of a resource state change, it just isn't always simpler. REST wouldn't give them much in this case as it's hard to imagine they'd make use of any of REST advantages. Not that there wouldn't be any technically (being able to evolve APIs without breaking clients is a pretty big advantage, plus plenty of other things), but that for their business it doesn't matter (they control every client).
  - michaelmior 12y ago
    You change the state of the horn to be on, but I'd imagine you might want the horn to automatically sound for a predefined length of time. Then the mapping is less obvious. Agreed that it doesn't really matter much in Tesla's case anyway.
    - dlisboa 12y ago
      You're still changing its state. If you have one horn you can do whatever you want with it, just like a normal person would. What the client does with a resource is only limited by the API, REST doesn't care what the messages contain. The semantic of the message is up to the API to resolve, you could encode that "stay on for 10 seconds" however you wanted.
deleted 12y ago
[deleted]
pornel 12y ago
Here's Roy Fielding's summary: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... After reading this I cringe whenever I see any API claiming to be "REST(ful)".
- chime 12y ago
  > A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling]. I don't even know how I'd write a client against a server that arbitrarily changes endpoint URIs. I honestly don't see a benefit of RESTful if REST requires complete decoupling of the server and client. REST isn't SOA. There is no discovery API for REST. If I don't get to hardcode /api/vehicle/, then how else can I write a functional client?
  - dlisboa 12y ago
    As with a lot of things in REST, the answer lies...in your browser. How did you know how to answer that last comment? You clicked a link for it. Not everything about REST can be answered by "just look at your browser", but a lot of things can. If you follow a link you don't care what the URL is. You never needed to type out "/reply" to use Hacker News, you don't need to do it to use an API. That's what the article is about. The actual URL is unimportant, you just need to know what the link for "/api/vehicle" returns to do something useful with it. Like you knew that "/reply" would give you a form with a place to type out a reply. > I don't even know how I'd write a client against a server that arbitrarily changes endpoint URIs. The thing is, you don't have to. I can write one for you and you'll never need to write another one again. You could use it and just have to implement the part that matters to your application, the semantic of it. You wouldn't need to hardcode anything, or even handle URIs at all. You could use it for Tesla's API, Twitter's, Facebook's, whatever. If they used links you could use the exact same client for anyone, just needing to re-write the logic part (like creating a post on Facebook, a tweet on Twitter, etc). Problem is hardly anyone actually implements links so you can't do that. It sounds like utopia but it's just the product of extreme decoupling. It's not really any different than browsers.
timdorr 12y ago
(Project owner here) My fault for calling it that. It's REST-ish, but not RESTful. Tesla never called it that (they don't even officially acknowledge the API), so it shouldn't be misconstrued as them not knowing what REST is. This is their internal API for the mobile apps, so they're free to design it however they like.
- aroman 12y ago
  How is it REST-ish, even?
  - deleted 12y ago
    [deleted]
  - timdorr 12y ago
    True. This always comes up whenever it gets posted here or on Reddit, so I just renamed it to the "Model S JSON API" to stop that argument from coming up again.
    - heezo 12y ago
      I use this API daily. I agree with some of the others. It works. I don't really care if it's REST or not. Of course, if the API is going to be growing, you may want to organize it in a guessable format...also, if it's going to be growing, I wouldn't mind helping/testing. :D
deleted 12y ago
[deleted]
coherentpony 12y ago
> Very few concepts have been so hugely corrupted to mean exactly the opposite of what they mean as REST. This is probably the least REST API in existence. This is the first time I've seen URL APIs not being referred to as RESTful. What makes it non-RESTful?
- steveklabnik 12y ago
  It's not according to both RESTs: Fielding's REST says absolutely nothing about URLs or their structure. Everyone else's REST (and, the HTTP spec) says that you shouldn't use GET to cause a side effect.
zak_mc_kracken 12y ago
Most people use REST as a synonym for "API you can call over HTTP". I've never liked the dogmatic aspect of REST anyway, saying that API's should only ever be REST-ful is like saying that you should never call functions in your programs and only ever use getters and setters.

by dlisboa 12y ago

gregory144 12y ago

I agree with you, but I have trouble understanding the right way to implement "commands" like this - I must be thinking about it in the wrong way. How would you design a "real" REST interface for a command like this? What's the advantage a "real" REST interface gives you in this case?

benregenspan 12y ago
Exactly -- where does something that is designed for "state transfer" get you when the goal is to only temporarily modify a state/send a command that modifies internal state for X amount of time, not really "transfer" one at all? REST maps very nicely to CRUD operations, but not to this.
- zachrose 12y ago
  Sure, but maybe you could think of POSTing to /honks as "creating a honk." This would make sense if you wanted to GET /honks and see a collection of previous honks. (Modifying an existing honk doesn't make sense, so we wouldn't have to worry about it.)
  - andrewstuart2 12y ago
    I wouldn't mind performing GET /vehicle/{id}/honks?since={time}&limit=1000 to see an indicator of how aggressively my car has been driven. Especially if somebody else is driving it.
  - shawnz 12y ago
    I think this interpretation is the best fit. Similarly PUT would be appropriate for requests where you are specifying the time that the honk should occur, which would make them idempotent.
benregenspan 12y ago
(That said, they should definitely use POST here!)
jholman 12y ago
Right. REST is about Transfering the State's REpresentation. In this case, we want to transfer an event ("honk!"). You could argue that we want to transfer a state transition ("begin honking"), and let some other process (the car) handle the next transition ("cease honking") independently, but that's forced, and in any case it's not RESTful either. As far as I can tell, REST is appropriate in very few cases.... although it IS appropriate for more cases than it might first appear.
chrisrogers 12y ago
You would use RPC.
- icambron 12y ago
  This. While this API is not RESTful at all, that's just a nomenclature problem; it's totally fine as an API [1]. RPC is perfectly appropriate for a wide range of problems and there's no need to shoehorn every application into REST just because people say It's the Thing to Do. I could imagine a RESTful API for this, as people have above, and it might work well. But it isn't some sort of obvious best practice. [1] Except that it really ought to use POST.
andrewstuart2 12y ago
I don't know the whole state of the vehicle. I don't want to. So I'll use PATCH. I know I want the horn to be in a honking state and remain in that state for 1 second. The implementation is responsible for doing what it needs to do in order to get the resource into the state (or differential state in this case) I told it to take. I'm not usually in favor of nested API design, but complex resources like cars make sense, so: PATCH /vehicles/{id}/horn { "enabled": true, "timeRemaining": 1000 }
- SilasX 12y ago
  My initial thought would be that a request for a "honk action" is not idempotent, so it should be a POST. You could do it as a PUT or PATCH, but you'd have to do it differently from in your example in order to preserve idempotence, due to the complications of working with time. Remember, if the request successfully goes through twice that should have the same effect as if only the first succeeded. One way to accomplish that would be to give an absolute start and end time for honk to be on. e.g., PUT /vehicles/{id}/horn { "enabled": true, "time_start": "2014-04-12T20:12:36.1", "time_end": "2014-04-12T20:12:36.6"} for a half-second honk.
dlisboa 12y ago
There are some ways, I'm just thinking off the top of my head for one here. If the resources of the car were mapped and had states it could work fine with a full REST interface. You could change the state of the horn like you change the state of a switch. You'd change the horn to be "on", not call some "turn it on" procedure. They have some indications of that. There's a URL that returns the state of the vehicle (driving and position). That's something that could be mapped as a first-class citizen and someone could mess with it with the semantics of the verbs. Commands are a much more RPC area though, REST doesn't map perfectly. You can almost always make a command into something of a resource state change, it just isn't always simpler. REST wouldn't give them much in this case as it's hard to imagine they'd make use of any of REST advantages. Not that there wouldn't be any technically (being able to evolve APIs without breaking clients is a pretty big advantage, plus plenty of other things), but that for their business it doesn't matter (they control every client).
- michaelmior 12y ago
  You change the state of the horn to be on, but I'd imagine you might want the horn to automatically sound for a predefined length of time. Then the mapping is less obvious. Agreed that it doesn't really matter much in Tesla's case anyway.
  - dlisboa 12y ago
    You're still changing its state. If you have one horn you can do whatever you want with it, just like a normal person would. What the client does with a resource is only limited by the API, REST doesn't care what the messages contain. The semantic of the message is up to the API to resolve, you could encode that "stay on for 10 seconds" however you wanted.

deleted 12y ago

[deleted]

pornel 12y ago

Here's Roy Fielding's summary: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... After reading this I cringe whenever I see any API claiming to be "REST(ful)".

chime 12y ago
> A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling]. I don't even know how I'd write a client against a server that arbitrarily changes endpoint URIs. I honestly don't see a benefit of RESTful if REST requires complete decoupling of the server and client. REST isn't SOA. There is no discovery API for REST. If I don't get to hardcode /api/vehicle/, then how else can I write a functional client?
- dlisboa 12y ago
  As with a lot of things in REST, the answer lies...in your browser. How did you know how to answer that last comment? You clicked a link for it. Not everything about REST can be answered by "just look at your browser", but a lot of things can. If you follow a link you don't care what the URL is. You never needed to type out "/reply" to use Hacker News, you don't need to do it to use an API. That's what the article is about. The actual URL is unimportant, you just need to know what the link for "/api/vehicle" returns to do something useful with it. Like you knew that "/reply" would give you a form with a place to type out a reply. > I don't even know how I'd write a client against a server that arbitrarily changes endpoint URIs. The thing is, you don't have to. I can write one for you and you'll never need to write another one again. You could use it and just have to implement the part that matters to your application, the semantic of it. You wouldn't need to hardcode anything, or even handle URIs at all. You could use it for Tesla's API, Twitter's, Facebook's, whatever. If they used links you could use the exact same client for anyone, just needing to re-write the logic part (like creating a post on Facebook, a tweet on Twitter, etc). Problem is hardly anyone actually implements links so you can't do that. It sounds like utopia but it's just the product of extreme decoupling. It's not really any different than browsers.

timdorr 12y ago

(Project owner here) My fault for calling it that. It's REST-ish, but not RESTful. Tesla never called it that (they don't even officially acknowledge the API), so it shouldn't be misconstrued as them not knowing what REST is. This is their internal API for the mobile apps, so they're free to design it however they like.

aroman 12y ago
How is it REST-ish, even?
- deleted 12y ago
  [deleted]
- timdorr 12y ago
  True. This always comes up whenever it gets posted here or on Reddit, so I just renamed it to the "Model S JSON API" to stop that argument from coming up again.
  - heezo 12y ago
    I use this API daily. I agree with some of the others. It works. I don't really care if it's REST or not. Of course, if the API is going to be growing, you may want to organize it in a guessable format...also, if it's going to be growing, I wouldn't mind helping/testing. :D

deleted 12y ago

[deleted]

coherentpony 12y ago

> Very few concepts have been so hugely corrupted to mean exactly the opposite of what they mean as REST. This is probably the least REST API in existence. This is the first time I've seen URL APIs not being referred to as RESTful. What makes it non-RESTful?

steveklabnik 12y ago
It's not according to both RESTs: Fielding's REST says absolutely nothing about URLs or their structure. Everyone else's REST (and, the HTTP spec) says that you shouldn't use GET to cause a side effect.

zak_mc_kracken 12y ago

Most people use REST as a synonym for "API you can call over HTTP". I've never liked the dogmatic aspect of REST anyway, saying that API's should only ever be REST-ful is like saying that you should never call functions in your programs and only ever use getters and setters.