provide api documentation

Bug #817578 reported by Ricardo Kirkner
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Canonical SSO provider
Confirmed
Low
Unassigned
Ratings and Reviews server
Invalid
Low
Unassigned
Software Center Agent
Fix Released
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?)

Revision history for this message
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.

Revision history for this message
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.

Revision history for this message
Michael Nelson (michael.nelson) wrote : Re: [Bug 817578] Re: provide api documentation

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.

Revision history for this message
Stuart Metcalfe (stuartmetcalfe) wrote :

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
Revision history for this message
Anthony Lenton (elachuni) wrote :

I believe this isn't fixed yet.

Revision history for this message
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
Revision history for this message
Adam Collard (adam-collard) wrote :
Changed in software-center-agent:
status: Confirmed → Fix Released
Changed in rnr-server:
status: Confirmed → Invalid
Changed in canonical-payment-service:
status: Confirmed → Invalid
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.