Summary

Add a WebAPIResource class for creating more RESTful APIs.

Review Request #1528 — Created April 21, 2010 and submitted

Information

Owner

chipx86

Repository

Djblets

Branch

master

Bugs

Depends On

Reviewers

Groups

djblets, reviewboard

People

Description

Add a WebAPIResource class for creating more RESTful APIs.

This introduces a new class for easily creating RESTful URL resources
that can handle standard HTTP methods and return meaningful data in a
nicely constructed hierarchy.

By using WebAPIResource, a site can offer a very clean set of URLs to
work with any object.

There's a lot to this object, but it's all covered in the extensive
documentation in webapi/resources.py.

Review Board will be using this for its new more RESTful API.

There's more I want to do for this soon, such as automatic documentation
generation and proper mimetype detection, but I wanted to get this in
as a base first.

Testing Done

Tested this with my upcoming Review Board change for the web API.

Change Summary:

* Removed action support. This isn't very RESTful and we don't actually need it in Review Board. No sense in having an extra feature just for the sake of it.
* Added a @webapi_request_fields decorator that allows a get/update/create handler specify and validate optional and required parameters in the request. This also provides some documentation for the fields, which will be able to be introspected for automatic documentation generation.
* Added automatic parent resource calculation, removing the need to create the complex get_href_parent_ids functions. Now a single model_parent_key variable just needs to be set on a resource.
* Added properties that can be overridden for the result keys for objects and lists and the resource name in the URI.
* Added a RootResource class that makes it easy to create a root resource linking to top-level resources in a tree. This is browseable.
* Made it easier to have resources that don't require Django models.
* Added has_modify_permissions to UserResource.
* Renamed the instantiated userResource and groupResource variables to user_resource and group_resource.

Diff:

Revision 2 (+814 -38)

Show changes

	djblets/webapi/core.py
	djblets/webapi/decorators.py
	djblets/webapi/resources.py

Change Summary:

* Changed the representation for linked resources. Instead of 'child_hrefs', there's 'links', which contains all links to child resources as well as things that can be done on the current resources ('create', 'update', 'delete'). The values in this dictionary contain 'href' and 'method' (HTTP method) keys.
* Removed 'href' from resources and moved it to 'links' with a key of 'self'.
* Renamed the 'method=' query parameter to '_method='.
* Use WebAPIResponsePaginated for results from resources representing lists of objects.
* Updated WebAPIResponsePaginated to use the new links method above.
* Fixed type checking for @webapi_request_fields and validate the values, returning an error if they're invalid.
* Ensure that URIs for resources are represented the same way everywhere.

This is probably the last change for this review request. New functionality will be going in on top of this. I'm now happy with the base support for resources.

Diff:

Revision 3 (+953 -45)

Show changes

	djblets/webapi/core.py
	djblets/webapi/decorators.py
	djblets/webapi/resources.py

djblets/webapi/core.py (Diff revision 3)

Why not just have headers default to {}?

chipx86 May 2, 2010, 10:46 a.m.

I think the reason I did it was to not add stuff to the passed in headers dictionary in the case of it being the default {} (as those values would be used the next time), but I really should just copy the dictionary anyway, since it is being modified.

djblets/webapi/decorators.py (Diff revision 3)

Will 'method' or 'callback' ever be in supported_fields? If not, you can get rid of the check above.

chipx86 May 2, 2010, 10:48 a.m.

These are actually special parameters that are handled by the Djblets webapi code. They should never be in supported_fields, but we want to pretend they're valid anyway. I don't know if you meant the check that you commented on or the previous one, but I don't think I can get rid of either and have this work.

djblets/webapi/resources.py (Diff revision 3)
```
I assume you meant "Resources"?
```
1. chipx86 May 2, 2010, 10:48 a.m.
  Fixed.
djblets/webapi/resources.py (Diff revision 3)
```
Dostring?
```
1. chipx86 May 2, 2010, 10:50 a.m.
  Added.

Change Summary:

* Cleaned up get_href and made it require a request parameter. It should always get passed one, so there's no reason for it to be optional.
* Renamed get_links_for_resources to get_links.
* Added documentation for get_links.
* Resource names are now expected to use '_' instead of '-', with normalization to '-' happening for uri_name.
* Moved the encoders to encoders.py, and brought back the original code for BasicAPIEncoder, in order to maintain backwards-compatibility.
* Fixed the checks for determining when to call get_list in order to work with resources that don't have a Model, but do have a list of child resources.
* Check for "_method" in the decorator instead of "method", since it's been renamed.
* The headers dictionary in WebAPIResponseError now defaults to {} and is properly copied before modification in order to prevent data leaking into the passed in dictionary.

Diff:

Revision 4 (+996 -64)

Show changes

	djblets/webapi/core.py
	djblets/webapi/decorators.py
	djblets/webapi/encoders.py
	djblets/webapi/resources.py

Ship it!