[Pulp-list] RESTful Practices

[Jason L Connor]

On Thu, 2010-06-17 at 09:46 -0400, Jason Dobies wrote:
> ooks good, I'm glad we have this documented. A few comments:

Thanks for the feed back.

> 
> ----
> "JSON Encoding"
> 
> You might want to add a note in here about what happens when an error
> occurs on the server and how it is encoded.

Excellent suggestion, I'll add this.	

> 
> ----
> "No Exposed Documents"
> 
> I have no problem with doing it this way, I'm just curious what
> benefit
> it brings.

Nothing other than consistency and not having to change what's already
there. This is how I crafted the first urls and I want our api to be
very consistent in this regard.

> 
> ----
> "Domains"
> 
> Is "domains" a standard name in REST for this sort of thing? Since
> we're
> dealing in URLs that will have a domain name, we might want to use
> "namespace" or something similar instead of domain.

This is an excellent point. Domains is confusing. How about 'top-level'
object collections?

> 
> ----
> "Querying Objects..."
> 
> "or a Null (None in Python) if no such repository exists. " - What
> does
> that look like in JSON? Is it just {} ?
> 
> ----
> "Filtering"
> 
> We may need a convention for differentiating different levels of
> detail
> in objects. For instance, there may be a case where we only need a
> repo's metadata instead of all of its relationships too (in cases
> where
> we actually use relationships).
> 
> This may not be an issue, I may be applying lazy loading/SQL database
> concepts where they don't apply in MongoDB. Just throwing it out
> there.

I perhaps adding a 'defer' keyword filter? for example:
/repositories/?defer=arch&defer=feed

I'm not sure we really need this...

> 
> ----
> "Object Deletion"
> 
> "To delete an existing object, a DELETE request is sent to that
> object's
> URL."
> 
> The idea of an object's URL means using the ID for that object? Which
> ID, the mongo one or a logical ID?

An objects URL is the same one used for getting info on a single object.
I guess this isn't as clear as I'd like it to be. I'll add some
clarification.

> 
> ----
> "Web Service Responses"
> 
> I mentioned this above, but we should document what to expect in the
> case of a server error. Will a 500 be returned?
> 
> Also, I'm guessing 403s will be returned when we have auth in place? 

Yes, we'll add 403 as we get authentication in place. And I'll add the
500 stuff at the beginning of the general conventions with a back
reference to it in this section.

-- 
Jason L Connor
Senior Software Engineer
Systems Management and Cloud Enablement
Red Hat, Inc.
+1.919.890.8331
Freenode: linear
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/pulp-list/attachments/20100617/c0ffac4f/attachment.sig>