On 03/03/2010 03:13 PM, Devan Goodwin wrote:
On Wed, Mar 3, 2010 at 2:25 PM, Bryan Kearneybkearney@redhat.com wrote:
PUTTING IT ALL TOGETHER
I think the following APIS which are docuemnted at:
https://fedorahosted.org/candlepin/wiki/API
would change
registerConsumer (aka POST /consumer): POST /consumers
unregisterConsumer (aka DELETE /consumer/{cosumer_uuid}): DELETE /consumers/{consumer_uuid}
syncCertificates (aka POST /consumer/{consumer_uuid}/certificates): POST /consumers/{consumer_uuid}/certificates This is a bit off standard, but I think we are ok
Indeed this one does seem a little off, we're doing the POST so the client can push up the serial numbers it already has, and the server can then return just the certificates that need updating. (to cut down on bandwidth IIRC)
However I think this is where the HTTP HEAD method is meant to be used, we would expose:
/consumers/{uuid}/certificates (optional query param to list multiple ids/serials) /consumers/{uuid}/certificates/{certid/serial}
Supporting both GET/HEAD for each. HEAD would just return you the metadata (serial number, any data we need to know if it changed), whereas GET would also include the actual cert contents. Client has the option to make either method call on all certs, or a specific cert.
It would also likely mean we could clean up this CertificateStatus object which contains a Certificate.
If we're going to make the effort to clean this up proper and make it "restful" I'd like to pitch we make this change as well.
NOTE: this transfer the responsibility for determine what gets thrown out and what doesn't from the server to the client tools. I think this is a good thing, rather than the client saying "here's what's on the box, you figure out what I need, and send me instructions on what to do with each which I'll act on", the client would now say "what should I have and I'll act on that" and then acts on those results. To me this seems more logical.
Let me read some more about HEAD. I am all for figuring out all but this one.
bind: POST /entitlement/consumer/{consumer_uuid}/product/{product_id} becomes POST /consumers/{consumer_uuid}/entitlements?product={product_id}
POST /entitlement/consumer/{consumer_uuid}/token/{registration_token} becomes POST /consumers/{consumer_uuid}/entitlements?token={registration_token} POST /entitlement/consumer/{consumer_uuid}/pool/{pool_id} becomes POST /consumers/{consumer_uuid}/entitlements?pool={pool_id}
Only part of this I'm wondering about, should those be query params or form params? I can't find any examples of using query params when doing a POST, I think that's usually passed in via the message body. Thoughts?
So... jersey if kinda lax because I think it allows form and query to be used interchangeablye (I think). I would be fine saying "parameter" for now :)
All of these should return a new entitlement
Agreed!
getEntitlementPools (aka GET /entitlementpools/consumer/{consumer_uuid}/ ): GET /pools?consumer={consumer_uuid}
GET /entitlement/consumer/{dbid}/: GET /consumers/{dbid}/entitlements or GET /entitlements?consumer={dbid}
GET /owner/{dbid}/entitlement: GET /owners/{dbid}/entitlements or GET /entitlements?owner=dbid
Many other changes, but all variations on the same theme.
Thoughts, Comments, Criticisms?
The "rest" looks good to me! :)
Cheers,
Devan