API clients or Rust about apis-client-generator

[Byron]

I have already made the necessary decisions, this issue can be closed. I'd do it myself, but for some reason I am not allowed to do so.

[aiuto]

Sorry. I never saw your initial post. Let me see if I understand your post correctly.

I'm not sure what you mean by the "Google API for Rust". Since you have contacted the people writing library generators, I take it to mean you are implementing a tool that uses Google Discovery to generate Rust libraries to talk to specific APIs. In that context, I am not sure if you intend to write a standalone generator in Rust (like the Go team), or to contribute a template based one to the system here.

The other thing you ask about is crates.io. I know nothing about the repository. I do not know if any other teams within Google intend to create projects within it. This project itself, would have no plans to push things there, because that would not sense in our context. This is just a tool for generating code.

That aside, I am not sure exactly what your concern is. You say names rather than name, but do not give an idea of how many and for what? If you intended to create a package for every Google API, I would advise you that this is a no-win proposition. The APIs change often and have many silent slight revisions. Unless you build automatic tooling to detect changes and auto-publish the libraries you are always going to be behind what is current.

[Byron]

Thanks for the reply. The initial question was indeed about whether or not you intended to publish your own crates to crates.io, which would have made name-clashes with my crates a possibility. I didn't want to 'take' good names from you, that's all.

The project I referred to is implementing a code generator to build Rust APIs (and commandline tools) automatically based on the latest data from Google Discovery. Therefore it's easy to generate and re-publish new versions to stay rather up-to-date.

But can you really call it a 'no-win' position ? Even outdated bindings should remain operational and useful unless there is a major revision change, e.g. going from youtube3 to youtube4 without backward compatibility.

As a side-note: Did you know that it seems quite common that the API revisions change, without changing anything else within the json file ? Is this a bug ? Or is the provided json filtered, and Google keeps more data about these APIs internally which in these cases may indeed have changed ?

Thanks for your time

[aiuto]

On Sat, Apr 11, 2015 at 9:00 AM, Sebastian Thiel [email protected]
wrote:

Thanks for the reply. The initial question was indeed about whether or not
you intended to publish your own crates to crates.io, which would have
made name-clashes with my crates https://crates.io/search?q=google a
possibility. I didn't want to 'take' good names from you, that's all.

The project I referred to https://github.com/Byron/google-apis-rs is
implementing a code generator to build Rust APIs (and commandline tools)
automatically based on the latest data from Google Discovery. Therefore
it's easy to generate and re-publish new versions to stay rather up-to-date.

But can you really call it a 'no-win' position ? Even outdated bindings
should remain operational and useful unless there is a major revision
change, e.g. going from youtube3 to youtube4 without backward
compatibility.

​Backwards compatibility of minor changes depends on how you handle data
and apply the API. Let's say your programs does a get, change a field, put
sequence. Now, if an API change adds a new field to an object, and
your library does not silently handle fields you did not expect, then you
could up with code that read the object, then tried to rewrite without the
field, causing data loss. The trick is that you have to make the commitment
in your library design to gracefully handle data that you might not have
expected when the library was generated. That can be tricky.

When I build client applications, I generate the library surface live each
time, from a discovery which is as recent as possible (modulo not doing
HTTP calls out in the middle of a build).

As a side-note: Did you know that it seems quite common that the API

revisions change, without changing anything else within the json file ? Is
this a bug ?

​I'm not sure how the revision field in discovery gets generated. It looks
like a date, so I would guess that is the date the description was
published. Our own library publishing system diffs discovery against the
previous and generates its own revision #, which increments up from 1.

Or is the provided json filtered, and Google keeps more data about these
APIs internally which in these cases may indeed have changed?

Thanks for your tim
​e​

[Byron]

Indeed, handling Json fields properly is still something I don't do correctly, as calls will fail in case there are unknown fields coming from the server (instead of just ignoring them, for example). Unfortunately this is something I can't currently fix as I depend on another library for json decoding. However, failure is probably the better strategy instead of allowing said data-loss.

Nonetheless I am optimistic that most common operations, like uploads to YouTube, will work for a while without having to rebuild the tool every few days.

It's interesting that you do internally what I would have done if I wanted to precisely track changes in the documents given by the Discovery API. It's a bit unfortunate that the revision cannot be trusted to reflect a real change, which will force you to diff the actual json structure against the previous known one to be sure there actually is a change.