Move docs off of Apiary about tesla-api

[jamietownsend]

I put together a swagger file (quite a while ago now and haven't updated it with newer stuff I don't currently need). You can find a copy under https://github.com/jamietownsend/tesla-java-client/blob/master/swagger-tesla-api.yaml

[mseminatore]

Happy to help out as I've both used and valued your work! I am particularly interested in seeing the calendar functionality documented.

What are you proposing as a replacement for the mock server? I just started work to use a fork of the mock server for testing purposes.

[timdorr]

There shouldn't be a mock server. The fact that Apiary has one is simply a side effect of using their service. However, it doesn't properly mock the Tesla API (nor should it; it's non-conforming to REST), so it's misleading to use that one.

Nor do I think we should be setting up a mock server system. That's what I use VCR for in the ruby parts of this project. That way I can test against the real API surface without continually hammering them with requests.

[timdorr]

Started some initial work here: https://timdorr.github.io/model-s-api/

Source lives here: https://github.com/timdorr/model-s-api/tree/master/docs

[mseminatore]

What do you record using VCR? Do you record and playback a full test pass session against Tesla servers?

…

On Sun, Nov 27, 2016 at 11:34 AM, Tim Dorr ***@***.***> wrote: There shouldn't be a mock server. The fact that Apiary has one is simply a side effect of using their service. However, it doesn't properly mock the Tesla API (nor should it; it's non-conforming to REST), so it's misleading to use that one. Nor do I think we should be setting up a mock server system. That's what I use VCR for in the ruby parts of this project. That way I can test against the real API surface without continually hammering them with requests. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#42 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AQDQuIk8iVkBLKhi01Yv3Y7TZB4lScV_ks5rCdtEgaJpZM4K8ycG> .

[timdorr]

Yep, and I only have to record once because VCR immediately saves the request for any subsequent runs. Only if I change how I call the API will trigger a re-recording (which will error out until I clear the cassette file, so that I don't accidentally hammer their servers).

[mseminatore]

Gotcha. I like the basic concept of capture/playback. But doesn't that leave your personal info (login credentials, tokens, etc.) in the cassettes? I must be missing something.

…

On Mon, Nov 28, 2016 at 1:38 PM, Tim Dorr ***@***.***> wrote: Yep, and I only have to record once because VCR immediately saves the request for any subsequent runs. Only if I change how I call the API will trigger a re-recording (which will error out until I clear the cassette file, so that I don't accidentally hammer their servers). — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#42 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AQDQuO7rZ-f7ru-60I06ItIV1Ze8mbV_ks5rC0m5gaJpZM4K8ycG> .

[timdorr]

They're filtered from the cassette file

[timdorr]

Welp: https://www.oracle.com/corporate/acquisitions/apiary/index.html

(Swear I didn't know about this ahead of time! Congrats to the Apiary folks!)

[jonasman]

have you thought about openapi3 (swagger) documentation?

[timdorr]

It's not OpenAPI-compliant, as far as I can tell.

[jonasman]

i think 3.0 is openapi, swagger was 2.0. https://github.com/OAI/OpenAPI-Specification

[timdorr]

After messing around with Jekyll far too much, I'm throwing in the towel and just using Gitbook instead. We use it over on Redux and it's worked very well for us so far. It gives a good reading experience both on their site and here on GitHub (and locally as well). Check it out: https://timdorr.gitbook.io/tesla-json-api/

[timdorr]

Update: Put it under my personal domain: https://tesla-api.timdorr.com/ I've also put a notice at the top of the old docs. I'll clear them out and mark this closed as soon as everything is moved over.

[timdorr]

OK, it's all moved over! 🎉