django-rest-framework document API в OPTIONS

Question

Я пишу свой первый REST API (с django-rest-framework).

Я добавляю параметры URL для фильтрации результатов. Я понимаю, что документация этих параметров принадлежит глаголу OPTIONS. Мой код:

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 

Это лучший/только REST путь (объясняя, что параметры находятся в OPTIONS)?

Что касается django-rest-framework, я расширил метаданные (self, request), которые чувствуют себя взломанными. Пропустил ли я какой-то встроенный способ установки описаний параметров?

Спасибо!

Answer 1

Общие представления уже включают описания параметров в ответ на запросы OPTIONS.

Например, после завершения учебного курса вы должны иметь возможность делать запросы OPTIONS и проверять доступные действия.

Обязательно установите параметр --user существующему пользователю/паролю или у вас будет только доступ только для просмотра и не получите часть ответа от actions.

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" 
      } 
     } 
    } 
} 

Вы также можете сделать OPTIONS запросы через просматриваемого API.