openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

On Aug 28, 2010, at 10:21 AM, Michael Barton wrote:

On Fri, Aug 27, 2010 at 11:05 AM, Jorge Williams <jorge.williams@xxxxxxxxxxxxx<mailto:jorge.williams@xxxxxxxxxxxxx>> wrote:
Sure,

We're aiming for consistency with our public APIs so that:

1) Collections are handled consistently
     a)  Pagination works the same across APIs
     b)  Filtering works the same way across APIs
2) URIs are built in the same manner
     a)  Versioning is handled the same way
     b)  URIs follow a consistent pattern
3) Error conditions are handled consistently
     a)  HTTP error codes are mapped in a consistent manner
     b)  Error info is return in the content of the message in the format
4) Special features should be included in every API and handled consistently
    a) Queryable Rate Limits
    b) Changes-since operations
5) Authentication/Authorization...
6) Polling operations and events...
etc...


This kind of worries me.  Lots of this stuff is going to vary between services, and I think we need to leave plenty of room for APIs to be informed by their domains and implementations.

Something like pagination may seem like we could standardize across services, but the Swift and Cloud Servers APIs already use completely different methods for paginating.  Probably for good reasons on both sides.

We can always make exceptions if there's good reason for it -- let's have those conversations as they come up.

I see standardization as being extremely beneficial.  Having a common language framework is one example of how standardization can help us, but it's important to also think of this from the perspective of our clients -- why should they have to learn 10 different ways of doing the same thing?

-jOrGe W.


Confidentiality Notice: This e-mail message (including any attached or
embedded documents) is intended for the exclusive and confidential use of the
individual or entity to which this message is addressed, and unless otherwise
expressly indicated, is confidential and privileged information of Rackspace. 
Any dissemination, distribution or copying of the enclosed material is prohibited.
If you receive this transmission in error, please notify us immediately by e-mail
at abuse@xxxxxxxxxxxxx, and delete the original message. 
Your cooperation is appreciated.