RFC: API changes

Bryan Kearney bkearney at redhat.com
Fri Mar 5 14:55:37 UTC 2010


On 03/05/2010 09:50 AM, Jesus M. Rodriguez wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 03/05/2010 08:48 AM, Devan Goodwin wrote:
>> On Wed, Mar 3, 2010 at 4:13 PM, Devan Goodwin<dgoodwin at rm-rf.ca>  wrote:
>>>> 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.
>>
>> This went *almost* according to plan, turns out HTTP HEAD requests
>> cannot return a message body, meaning you can only stuff metadata into
>> HTTP headers. In our case we're returning a list, which to me isn't a
>> great fit for headers and it'd probably reasonably easy to hit a
>> length limit.
>>
>> Instead I did it as a separate call, getCertificateMetadata.
>>
>> Code isn't yet pushed, just adding the ability to do
>> /consumer/{uuid}/certificates?serials=serial1,serial2,serial3 now.
>>
>> Wiki updated, Prad/Jeff could you guys let me know if this looks ok or
>> if there's anything else you guys need from it?
>> https://fedorahosted.org/candlepin/wiki/API
>>
>> During this I trimmed down ClientCertificateStatus / ClientCertificate
>> / ClientCertificateSerialNumber / Bundle to just ClientCertificate and
>> ClientCertificateMetadata. (former inherits from the latter)
>
> Would it be better to have a serial number resource which the client
> makes a GET request against (no params except maybe consumer_uuid)
> which would return ALL serial numbers, then let the client do the
> diff making a request for any missing certificates?
>
> GET /consumer/{consumer_uuid}/serialnumbers/
>

Or.. look at slide 10 of this:

http://blog.linkedin.com/2009/07/08/brandon-duncan-java-one-building-consistent-restful-apis-in-a-high-performance-environment/

-- bk



More information about the candlepin mailing list