provide api documentation

If we just had a plain REST api, I can see how this would be necessary. But if we supply a piston-miniclient python client for the API, IMO that's better than documentation (as I can try it against a staging service etc.), irrespective of which language I'm writing my own client with. But yep, even better if we can *also* generate readable/printable docs from the piston-miniclient client.

We have written a 'mock server' (actually more of an interception of the rnr client) for software center that we use to test various reviews changes in software center without hitting a real server (and offline). I did find myself looking at the rnr-server and rnrclient code alot when doing this, which makes me think this documentation would be a good idea for anyone else tring to write a mock implementation.

On Fri, Aug 5, 2011 at 12:17 AM, Aaron Peachey <email address hidden> wrote:
> We have written a 'mock server' (actually more of an interception of the
> rnr client)  for software center that we use to test various reviews
> changes in software center without hitting a real server (and offline).
> I did find myself looking at the rnr-server and rnrclient code alot when
> doing this, which makes me think this documentation would be a good idea
> for anyone else tring to write a mock implementation.

Hey Aaron! Yeah, we had a discussion the other week about whether we
should be providing mock servers as part of the projects, to allow
easy integration for users of the APIs. Interesting thinking about the
client though... given that we're providing piston-miniclients such as
rnrclient, we could possibly ship rnrclient together with
rnrclient_mock, which is configurable, but where all the calls return
sensible (configurable) values.

That would allow us on the server side to ensure that both rnrclient
and rnrclient_mock satisfy the server API, and users of the API to
write tests against the mock client. Just a thought.

Confirmed, although what form this documentation takes is open to discussion. As Michael points out, using piston makes this less of an issue and we should also be providing mocks of our own services (imho). In an ideal world, this would just be a meta bug to remind us to write documentation as we create and update our APIs.

I believe this isn't fixed yet.

This still needs to happen according to Achuni. More of an update than a complete write up.

https://dashboard.snapcraft.io/docs/