provide api documentation

Bug #817578 reported by Ricardo Kirkner on 2011-07-28
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Canonical SSO provider
Low
Unassigned
Payment service
Low
Unassigned
Ratings and Reviews server
Low
Unassigned
Software Center Agent
Low
Unassigned

Bug Description

We need documentation about our APIs so that consumers of them can know how to interact with our services.

This should also allow them to write mock servers to aid during unit testing.

Ideally, this documentation should get automatically generated from code (docstrings?)

Michael Nelson (michael.nelson) wrote :

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.

Aaron Peachey (aaronp) 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.

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.

Changed in canonical-identity-provider:
status: New → Confirmed
Changed in canonical-payment-service:
status: New → Confirmed
Changed in rnr-server:
status: New → Confirmed
Changed in software-center-agent:
status: New → Confirmed
Changed in canonical-identity-provider:
importance: Undecided → Medium
Changed in canonical-payment-service:
importance: Undecided → Medium
Changed in rnr-server:
importance: Undecided → Medium
Changed in software-center-agent:
importance: Undecided → Medium
Anthony Lenton (elachuni) wrote :

I believe this isn't fixed yet.

Dave Morley (davmor2) wrote :

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

Changed in canonical-identity-provider:
importance: Medium → Low
Changed in canonical-payment-service:
importance: Medium → Low
Changed in rnr-server:
importance: Medium → Low
Changed in software-center-agent:
importance: Medium → Low
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers