OPTIONS中的django-rest-framework文档API

Question

I'm writing my very first REST API (with django-rest-framework).

I'm adding URL parameters to filter the results. My understanding is that these parameters' documentation belongs in the OPTIONS verb. My code:

class SuburbViewSet(viewsets.ReadOnlyModelViewSet):
    """
    Retrieves the suburbs (20 per page).
    GET and OPTIONS allowed.
    """
    model = Suburb
    serializer_class = SuburbSerializer

    def get_queryset(self):
        """
        Can filter by region_id, ...
        - using query parameters in the URL.
        """
        queryset = Suburb.objects.all()
        region_id = self.request.QUERY_PARAMS.get('region_id', None)
        if region_id is not None:
            queryset = queryset.filter(region_id=region_id)
        return queryset

    def metadata(self, request):
        ret = super(SuburbViewSet, self).metadata(request)

        ret['parameters'] = {
            "page": {
                "type": "integer",
                "description": "The page number",
                "required": False
            },
            "region_id": {
                "type": "integer",
                "description": "The region ID to filter the results",
                "required": False
            }
        }

        return ret

Is that the best/only REST way to go (explaining what the parameters are in the OPTIONS)?

Concerning django-rest-framework, I've extended metadata(self, request) which feels hacky. Did I miss some built-in way to set the parameters descriptions?

Thanks !

Answer 1

The generic views already include parameter descriptions in response the OPTIONS requests.

For example, after completing the tutorial, you should be able to make OPTIONS requests and inspect the available actions.

Make sure to set the --user option to an existing user/password, or you'll only have ready-only access and won't get the actions part of the response.

bash: curl -X OPTIONS --user amy:amy -v http://127.0.0.1:8000/snippets/ -H 'Accept: application/json; indent=4'; echo
* About to connect() to 127.0.0.1 port 8000 (#0)
*   Trying 127.0.0.1... connected
* Server auth using Basic with user 'amy'
> OPTIONS /snippets/ HTTP/1.1
> Authorization: Basic YW15OmFteQ==
> User-Agent: curl/7.22.0 (x86_64-apple-darwin11.2.0) libcurl/7.22.0 OpenSSL/1.0.0e zlib/1.2.5 libidn/1.22
> Host: 127.0.0.1:8000
> Accept: application/json; indent=4
> 
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Date: Fri, 28 Jun 2013 09:27:01 GMT
< Server: WSGIServer/0.1 Python/2.7.2
< Vary: Accept, Cookie
< Content-Type: application/json; indent=4; charset=utf-8
< Allow: GET, POST, HEAD, OPTIONS
< 
{
    "name": "Snippet List", 
    "description": "This endpoint presents code snippets.\n\nThe `highlight` field presents a hyperlink to the hightlighted HTML\nrepresentation of the code snippet.\n\nThe **owner** of the code snippet may update or delete instances\nof the code snippet.\n\nTry it yourself by logging in as one of these four users: **amy**, **max**,\n**jose** or **aziz**.  The passwords are the same as the usernames.", 
    "renders": [
        "application/json", 
        "text/html"
    ], 
    "parses": [
        "application/json", 
        "application/x-www-form-urlencoded", 
        "multipart/form-data"
    ], 
    "actions": {
        "POST": {
            "url": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }, 
            "highlight": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }, 
            "owner": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }, 
            "title": {
                "type": "string", 
                "required": false, 
                "read_only": false, 
                "label": "title", 
                "max_length": 100
            }, 
            "code": {
                "type": "string", 
                "required": true, 
                "read_only": false, 
                "label": "code"
            }, 
            "linenos": {
                "type": "boolean", 
                "required": false, 
                "read_only": false, 
                "label": "linenos"
            }, 
            "language": {
                "type": "multiple choice", 
                "required": true, 
                "read_only": false, 
                "label": "language"
            }, 
            "style": {
                "type": "multiple choice", 
                "required": true, 
                "read_only": false, 
                "label": "style"
            }
        }
    }
}

You can also make OPTIONS requests via the browsable API.