Учебник 7: Схемы и клиентские библиотеки

Схема - это машиночитаемый документ, который описывает доступные конечные точки API, их URL-адреса и операции, которые они поддерживают.

Схемы могут быть полезным инструментом для автоматической генерации документации, а также могут использоваться для создания динамических клиентских библиотек, которые могут взаимодействовать с API.

Основной API

Для обеспечения поддержки схем фреймворк REST использует Core API.

Core API - это спецификация документа для описания API. Она используется для обеспечения внутреннего формата представления доступных конечных точек и возможных взаимодействий, которые API раскрывает. Он может использоваться как на стороне сервера, так и на стороне клиента.

При использовании на стороне сервера Core API позволяет API поддерживать рендеринг в широкий диапазон форматов схем или гипермедиа.

При использовании на стороне клиента, Core API позволяет создавать динамически управляемые клиентские библиотеки, которые могут взаимодействовать с любым API, раскрывающим поддерживаемую схему или формат гипермедиа.

Добавление схемы

REST framework поддерживает либо явно определенные схемы представлений, либо автоматически генерируемые схемы. Поскольку мы используем наборы представлений и маршрутизаторы, мы можем просто использовать автоматическую генерацию схем.

Вам потребуется установить пакет coreapi python, чтобы включить схему API, и pyyaml для преобразования схемы в широко используемый формат OpenAPI на основе YAML.

$ pip install coreapi pyyaml

Теперь мы можем включить схему для нашего API, включив автогенерируемое представление схемы в конфигурацию URL.

from rest_framework.schemas import get_schema_view

schema_view = get_schema_view(title='Pastebin API')

urlpatterns = [
    path('schema/', schema_view),
    ...
]

Если вы посетите конечную точку /schema/ в браузере, вы должны увидеть, что представление corejson стало доступно в качестве опции.

Schema format

Мы также можем запросить схему из командной строки, указав желаемый тип содержимого в заголовке Accept.

$ http http://127.0.0.1:8000/schema/ Accept:application/coreapi+json
HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/coreapi+json

{
    "_meta": {
        "title": "Pastebin API"
    },
    "_type": "document",
    ...

По умолчанию используется кодировка Core JSON.

Поддерживаются и другие форматы схем, такие как Open API (ранее Swagger).

Использование клиента командной строки

Теперь, когда наш API открывает конечную точку схемы, мы можем использовать динамическую клиентскую библиотеку для взаимодействия с API. Чтобы продемонстрировать это, давайте воспользуемся клиентом командной строки Core API.

Клиент командной строки доступен в виде пакета coreapi-cli:

$ pip install coreapi-cli

Теперь проверьте, что он доступен в командной строке…

$ coreapi
Usage: coreapi [OPTIONS] COMMAND [ARGS]...

  Command line client for interacting with CoreAPI services.

  Visit https://www.coreapi.org/ for more information.

Options:
  --version  Display the package version number.
  --help     Show this message and exit.

Commands:
...

Сначала мы загрузим схему API с помощью клиента командной строки.

$ coreapi get http://127.0.0.1:8000/schema/
<Pastebin API "http://127.0.0.1:8000/schema/">
    snippets: {
        highlight(id)
        list()
        read(id)
    }
    users: {
        list()
        read(id)
    }

Мы еще не аутентифицировались, поэтому сейчас мы можем видеть только конечные точки, доступные только для чтения, в соответствии с тем, как мы установили разрешения на API.

Давайте попробуем перечислить существующие фрагменты, используя клиент командной строки:

$ coreapi action snippets list
[
    {
        "url": "http://127.0.0.1:8000/snippets/1/",
        "id": 1,
        "highlight": "http://127.0.0.1:8000/snippets/1/highlight/",
        "owner": "lucy",
        "title": "Example",
        "code": "print('hello, world!')",
        "linenos": true,
        "language": "python",
        "style": "friendly"
    },
    ...

Некоторые конечные точки API требуют именованных параметров. Например, чтобы получить HTML-выделение для конкретного фрагмента, необходимо указать его идентификатор.

$ coreapi action snippets highlight --param id=1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
<head>
  <title>Example</title>
  ...

Аутентификация нашего клиента

Если мы хотим иметь возможность создавать, редактировать и удалять сниппеты, нам необходимо пройти аутентификацию как действительный пользователь. В данном случае мы просто используем базовую авторизацию.

Обязательно замените <username> и <password> ниже на ваше настоящее имя пользователя и пароль.

$ coreapi credentials add 127.0.0.1 <username>:<password> --auth basic
Added credentials
127.0.0.1 "Basic <...>"

Теперь, если мы снова получим схему, мы сможем увидеть полный набор доступных взаимодействий.

$ coreapi reload
Pastebin API "http://127.0.0.1:8000/schema/">
    snippets: {
        create(code, [title], [linenos], [language], [style])
        delete(id)
        highlight(id)
        list()
        partial_update(id, [title], [code], [linenos], [language], [style])
        read(id)
        update(id, code, [title], [linenos], [language], [style])
    }
    users: {
        list()
        read(id)
    }

Теперь мы можем взаимодействовать с этими конечными точками. Например, чтобы создать новый сниппет:

$ coreapi action snippets create --param title="Example" --param code="print('hello, world')"
{
    "url": "http://127.0.0.1:8000/snippets/7/",
    "id": 7,
    "highlight": "http://127.0.0.1:8000/snippets/7/highlight/",
    "owner": "lucy",
    "title": "Example",
    "code": "print('hello, world')",
    "linenos": false,
    "language": "python",
    "style": "friendly"
}

И удалить фрагмент:

$ coreapi action snippets delete --param id=7

Помимо клиента командной строки, разработчики могут взаимодействовать с вашим API с помощью клиентских библиотек. Клиентская библиотека для Python является первой из них, а в ближайшее время планируется выпуск клиентской библиотеки для Javascript.

Для получения более подробной информации о настройке генерации схем и использовании клиентских библиотек Core API вам необходимо обратиться к полной документации.

Анализ нашей работы

С невероятно малым количеством кода мы теперь имеем полноценный веб-интерфейс API pastebin, который полностью доступен для просмотра в Интернете, включает в себя клиентскую библиотеку на основе схемы, а также аутентификацию, разрешения для каждого объекта и несколько форматов рендеринга.

Мы прошли через каждый шаг процесса проектирования и увидели, что если нам нужно что-то настроить, мы можем постепенно перейти к использованию обычных представлений Django.

Вы можете просмотреть окончательный вариант tutorial code на GitHub, или попробовать живой пример в the sandbox.

Вперед и вверх

Мы подошли к концу нашего руководства. Если вы хотите принять более активное участие в проекте REST framework, вот несколько мест, с которых вы можете начать:

  • Вносите свой вклад в работу над GitHub, просматривая и отправляя проблемы, а также делая запросы на исправление ошибок.

  • Присоединяйтесь к `REST framework discussion group <https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework>`_** , и помогите создать сообщество.

  • Следите за the author в Twitter и передавайте привет.

А теперь идите и стройте удивительные вещи.

Вернуться на верх