IMHO, a well-documented WADL + XSD would say a thousand words (maybe more)... And can serve as a basis for automated testing as well. I understand that the v3 API draft is perhaps not at that stage yet; but, would like to see a WADL + XSD set as soon as the concepts are solidified.
Liem -----Original Message----- From: openstack-bounces+liem_m_nguyen=hp....@lists.launchpad.net [mailto:openstack-bounces+liem_m_nguyen=hp....@lists.launchpad.net] On Behalf Of Mark Nottingham Sent: Tuesday, June 12, 2012 8:43 PM To: Gabriel Hurley Cc: openstack@lists.launchpad.net Subject: Re: [Openstack] [keystone] v3 API draft (update and questions to the community) On 13/06/2012, at 1:24 PM, Gabriel Hurley wrote: > Totally agree with all of Jay's points, and I also couldn't agree more with > Mark on the importance of being crystal clear, and not operating on just a > "common understanding" which is quickly misunderstood or forgotten. > > Ideally I'd like to see an OpenStack API feature contract of some sort... > essentially a document describing the FULL list of features, how those > parameters are controlled and how they would interact, and what a project > should do if they do not implement an API feature (hopefully only for > technical reasons such as Keystone paging with LDAP or swift with complex > DB-esque operations). This isn't saying we should have a unified API spec, > I'm talking solely about a contract for the features all APIs should strive > to support. > > This would be a big project, but everyone would then have a common agreement > about what the user experience of interacting with OpenStack should be. The > project APIs as they stand are siloed and stunningly inconsistent, and I'd > love to work toward fixing that. Absolutely. One of my other projects is to rewrite the API as a proper specification (in a style similar to an Internet-Draft, not that we'd necessarily publish it as one). I should have something to show soon; if you're interested in helping out, that'd be great. Cheers, > My two cents, > > - Gabriel > >> -----Original Message----- >> From: openstack-bounces+gabriel.hurley=nebula....@lists.launchpad.net >> [mailto:openstack- >> bounces+gabriel.hurley=nebula....@lists.launchpad.net] On Behalf Of >> Mark Nottingham >> Sent: Tuesday, June 12, 2012 7:20 PM >> To: Jay Pipes >> Cc: openstack@lists.launchpad.net >> Subject: Re: [Openstack] [keystone] v3 API draft (update and questions to >> the community) >> >> >> On 13/06/2012, at 3:31 AM, Jay Pipes wrote: >> >>> This isn't necessarily true. Nova's compute layer goes through a number of >> steps to ensure a semi-transactional nature to certain operations like >> resizing. Certain times a query needs to indicate that it intends to make a >> reservation of resources (see quota/reservation system now .. this is the >> SELECT FOR UPDATE paradigm) and other times, the query doesn't care >> about such things. In the latter case, there aren't expectations that the >> list >> returned is 100% accurate according to the state of the database at a >> particular timestamp of when the transaction occurred. In this case, filters >> and optimistic pagination works perfectly fine, IMHO. >> >> That might work, but we need to be crystal-clear about the semantics of >> what we're giving back; having it understood between OpenStack projects >> isn't good enough. >> >> I.e., we're not building the APIs just for Horizon; they're for lots of >> folks, and >> subtle semantics -- even when well-documented, much less when they're >> not -- are often misunderstood. >> >> Cheers, >> >> -- >> Mark Nottingham http://www.mnot.net/ >> >> >> >> >> _______________________________________________ >> Mailing list: https://launchpad.net/~openstack >> Post to : openstack@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~openstack >> More help : https://help.launchpad.net/ListHelp > > > > _______________________________________________ > Mailing list: https://launchpad.net/~openstack > Post to : openstack@lists.launchpad.net > Unsubscribe : https://launchpad.net/~openstack > More help : https://help.launchpad.net/ListHelp -- Mark Nottingham http://www.mnot.net/ _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
