RFC: API changes
Bryan Kearney
bkearney at redhat.com
Wed Mar 3 18:25:35 UTC 2010
Per the IRC thread. He is a complete set of proposals with any backing
referneces I have for them. If we agree to any of these, I would suggest
we look to implement after this sprint in order to not scuttle the work
of the client guys:
1:: Plurals
-----------
No real reference, but is looks like most folks use /owners /customers
/jedi instead of /owner /customer /jedum.
2:: Put and POST
----------------
I think we are are ok, here, but look at:
-
http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/
-
http://en.wikipedia.org/wiki/Representational_State_Transfer#RESTful_web_services
- http://code.google.com/p/django-rest-interface/wiki/BestPractices
I think we want to go with the model of PUT being idempotent, and it is
used when you know "everything". If you know some thing, or need a query
parameter.. it is a POST.
3:: Rest is not RPC, Resource Addresability, URL Structure
---------------------------------------
This is a crap shoot of stuff, but looking at
-
http://blog.linkedin.com/2009/07/08/brandon-duncan-java-one-building-consistent-restful-apis-in-a-high-performance-environment/
- http://www.slideshare.net/calamitas/restful-best-practices (first part)
- http://code.google.com/p/django-rest-interface/wiki/BestPractices
It seems like we would want every resource would have a permanent uri
which is:
/{resources1}/{id}
And that we could provide readable uris for important relationships
/{resources1}/{id}//{resources2}/{id}
and adopt the pattern that collections can be filterable based on query
parameters:
/{resources1}?foo=bar
in part of this,
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
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}
All of these should return a new entitlement
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?
Next up, which can be done later, is
* HATEOAS
* Paginating Collections
* Versioning
-- bk
More information about the candlepin
mailing list