RFC: API changes

Devan Goodwin dgoodwin at rm-rf.ca
Wed Mar 3 20:13:49 UTC 2010


On Wed, Mar 3, 2010 at 2:25 PM, Bryan Kearney <bkearney at 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.

> 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?

>
>
>        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


-- 
Devan Goodwin <dgoodwin at rm-rf.ca>
http://rm-rf.ca



More information about the candlepin mailing list