Since we’re working on API implementation I started to think about client side implementation of API.
There are OpenAPI specification and a tool called Swagger, which could be used to automatically generate API clients basing on a specification: https://github.com/swagger-api/swagger-codegen
I never used this tool myself, but maybe some of our experts on web technologies know whether it worth the efforts to study this tool and then use it to generate API client for diaspora?
Maybe there are other similar tools exist, which are less famous than Swagger, but which might fit us better?
I didn’t use swagger myself yet, but we (other people) used it multiple time at work for different APIs, and it seems to be a pretty cool. So if I understand it correctly you can document the API with it, and it can generate interactive documentation for you, where you even can try the API And others can use it too to generate their clients too
So I wanted to convert our current draft-documentation to swagger some months ago … but time … but I think it’s definitely worth a try
I really liked Swagger years ago, as their documentation format was really nice to write and the results were really amazing. But some time in the past, they decided to remove all collaborative features (i.e. allowing others to edit) and only offer these in their commercial version, which is 15 USD per user per month. That was unfortunate, and as they have no special offer for open source projects, it is kinda dead to me.
These days, for diaspora* or other projects, I’d probably build something based on GitHub that runs ReDoc on Travis and pushes the result into a GitHub pages-served branch or so. That way, collaboration happens on GitHub via PRs with the usual access control flows, but we’d still end up with a nice interactive documentation.
As for generating API clients, I really dislike those tools. They work fine for generic stuff, but they have limits. A good API library is not just returning JSON objects, but is working the data into object structures that match the application design as well as the language they are designed in. This is stuff that needs to be done by hand. I used quite a few of those auto-generated libraries before, and I hated them every single time. It always felt like I was just getting a de-serialized JSON, and while that could be an okay-ish solution for something I built myself, I do not expect this kind of sloppyness from any official API.
For me, I’d rather have no official library and being forced to write a little JSON-requesting machine myself. If i see official API libraries for a project, I expect them to be nice, and not just some autogenerated stuff.
There were some good talks at RubyConf 2018 on auto-generating API generators that Google and other organizations use. I had it on my to do list to go back and look at setting them up with an example once the API was finished. I’m hand coding one in Kotlin to create an independent test harness but it is not meant to be a JVM-based implementation (although I guess it is). It will be interesting to explore so that any language could easily tie into the API. Again that’s for a little in the future though…
And others can use it too to generate their clients too 