GitHub 検索 Django RESTフレームワーク

ブラウザブルAPI

よく言われる格言ですが、何を言っているかを理解して考える習慣を身に付けなければならないというのは、非常に間違っています。実際には真逆です。文明は、思考せずに実行できる重要な操作の数を増やすことで発展します。

— アルフレッド・ノース・ホワイトヘッド、数学序論（1911年）

APIはアプリケーションプログラミングインターフェイスの略ですが、人間もAPIを読まなければなりません。誰かがプログラミングをしなければなりません。Django RESTフレームワークは、HTML形式がリクエストされたときに、各リソースに対応する、人間が簡単に読めるHTML出力を生成する機能をサポートしています。このページからリソースを簡単にブラウズできるほか、POST、PUT、DELETEを使用してリソースにデータを送信するためのフォームがあります。

URL

リソースの出力に完全修飾URLを含めると、「URL化」され、人間が簡単にクリックしてブラウズできるようにすることができます。rest_frameworkパッケージには、この目的のためのreverseヘルパーが含まれています。

フォーマット

初期状態では、APIはヘッダーで指定された形式を返します。ブラウザの場合、これはHTMLです。リクエストで?format=を使用すると形式を指定できます。そのため、URLに?format=jsonを追加すると、ブラウザで生のJSONレスポンスを表示できます。JSONを表示するための便利な拡張機能が、FirefoxとChromeにあります。

認証

閲覧可能なAPIに素早く認証を追加するには、名前空間「rest_framework」の下に「login」と「logout」という名前のルートを追加します。DRFは、urlconfに追加できるデフォルトのルートを提供します。

urlpatterns = [
    # ...
    url(r"^api-auth/", include("rest_framework.urls", namespace="rest_framework"))
]

カスタマイズ

閲覧可能なAPIはTwitterのBootstrap（v 3.4.1）を使用して構築されているため、ルックアンドフィールを簡単にカスタマイズできます。

デフォルトスタイルをカスタマイズするには、rest_framework/base.htmlから拡張されるrest_framework/api.htmlという名前のテンプレートを作成します。たとえば

テンプレート/rest_framework/api.html

{% extends "rest_framework/base.html" %}

...  # Override blocks with required customizations

デフォルトのテーマを上書き

デフォルトのテーマを置き換えるには、api.htmlにbootstrap_themeブロックを追加し、目的のBootstrapテーマCSSファイルへのlinkを挿入します。これにより、含まれているテーマが完全に置き換えられます。

{% block bootstrap_theme %}
    <link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css">
{% endblock %}

適切な既製の置換テーマはBootswatchで入手できます。Bootswatchのテーマを使用するには、テーマのbootstrap.min.cssファイルをダウンロードしてプロジェクトに追加し、上記の説明に従ってデフォルトのファイルを置き換えるだけです。新しいテーマのBootstrapバージョンがデフォルトテーマのバージョンと一致していることを確認してください。

bootstrap_navbar_variantブロックを使用して、デフォルトがnavbar-inverseのナビゲーションバーの変種を変更することもできます。空の{% block bootstrap_navbar_variant %}{% endblock %}は、元のBootstrapナビゲーションバースタイルを使用します。

完全な例

{% extends "rest_framework/base.html" %}

{% block bootstrap_theme %}
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@3.4.1/flatly/bootstrap.min.css" type="text/css">
{% endblock %}

{% block bootstrap_navbar_variant %}{% endblock %}

単にデフォルトのBootstrapテーマを上書きするよりも具体的なCSSの調整については、styleブロックを上書きできます。

Cerulean theme

Bootswatch 'Cerulean'テーマのスクリーンショット

Slate theme

Bootswatch 'Slate'テーマのスクリーンショット

カスタマイズ用のサードパーティ製パッケージ

自分で行うのではなく、サードパーティ製のパッケージを使用してカスタマイズできます。APIのカスタマイズ用のパッケージを2つ紹介します。

  • rest-framework-redesign - Bootstrap 5を使用したAPIのカスタマイズ用のパッケージです。モダンで洗練されたデザインで、ダークモードをサポートしています。
  • rest-framework-material - Django REST Frameworkのマテリアルデザインです。

Django REST Framework Redesign

rest-framework-redesignのスクリーンショット

Django REST Framework Material

rest-framework-materialのスクリーンショット

ブロック

api.htmlで使用できる閲覧可能なAPIベーステンプレートで使用可能なすべてのブロックです。

  • body - HTML全体の<body>。
  • bodyclass - <body>タグのクラス属性で、デフォルトでは空です。
  • bootstrap_theme - BootstrapテーマのCSS。
  • bootstrap_navbar_variant - ナビゲーションバーのCSSクラス。
  • branding - ナビゲーションバーのブランディングセクション。 Bootstrapのコンポーネントを参照してください。
  • breadcrumbs - リソースのネストを示すリンクで、ユーザーはリソースをさかのぼることができます。これらを保持することをお勧めしますが、breadcrumbsブロックを使用して上書きできます。
  • script - ページのJavaScriptファイル。
  • style - ページのCSSスタイルシート。
  • title - ページのタイトル。
  • userlinks - これはヘッダーの右にあるリンクのリストで、デフォルトではログイン/ログアウトリンクが含まれています。リンクを置き換えるのではなく追加するには、{{ block.super }}を使用して認証リンクを維持します。

コンポーネント

標準のBootstrapコンポーネントをすべて使用できます。

ツールチップ

閲覧可能なAPIは、Bootstrapツールチップコンポーネントを利用しています。js-tooltipクラスとtitle属性を持つ要素は、タイトルの内容がイベントのホバー時にツールチップを表示します。

ログインテンプレート

ブランディングを追加してログインテンプレートのルックアンドフィールをカスタマイズするには、login.htmlという名前のテンプレートを作成してプロジェクトに追加します（例：templates/rest_framework/login.html）。このテンプレートはrest_framework/login_base.htmlから拡張する必要があります。

ブランディングブロックを含めて、サイト名やブランディングを追加できます。

{% extends "rest_framework/login_base.html" %}

{% block branding %}
    <h3 style="margin: 0 0 20px;">My Site Name</h3>
{% endblock %}

また、api.htmlと同様にbootstrap_themeまたはstyleブロックを追加することでスタイルをカスタマイズできます。

高度なカスタマイズ

コンテキスト

テンプレートで利用できるコンテキスト

  • allowed_methods : リソースで許可されているメソッドのリスト
  • api_settings : API設定
  • available_formats : リソースで許可されているフォーマットのリスト
  • breadcrumblist : ネストされたリソースの連鎖に続くリンクのリスト
  • content : API応答のコンテンツ
  • description : リソースの説明、ドキュメント文字列から生成されます。
  • name : リソースの名前
  • post_form : POSTフォーム(許可されている場合)で使用されるフォームインスタンス
  • put_form : PUTフォーム(許可されている場合)で使用されるフォームインスタンス
  • display_edit_forms : POST、PUTおよびPATCHフォームを表示するかどうかを示すブール値
  • request : リクエストオブジェクト
  • response : レスポンスオブジェクト
  • version : Django REST Frameworkのバージョン
  • view : リクエストを処理するビュー
  • FORMAT_PARAM : ビューはフォーマットオーバーライドを受け入れます
  • METHOD_PARAM : ビューはメソッドオーバーライド受け入れます。

テンプレートに渡されるコンテキストをカスタマイズするには、BrowsableAPIRenderer.get_context()メソッドをオーバーライドできます。

base.htmlを使用しない

Bootstrapを使用しないまたはサイトの他の部分とさらに緊密に統合する方法などの高度なカスタマイズの場合、api.htmlをbase.htmlに拡張しないように選択できます。その後、ページのコンテンツと機能は完全にあなた次第です。

ChoiceFieldの大量のアイテムによる処理

関係またはChoiceFieldにアイテムが多すぎると、すべてのオプションを含むウィジェットをレンダリングすると非常に遅くなり、ブラウザーAPIのレンダリングのパフォーマンスが低下します。

この場合の最も簡単なオプションは、select入力を標準のテキスト入力に置き換えることです。例：

 author = serializers.HyperlinkedRelatedField(
    queryset=User.objects.all(),
    style={'base_template': 'input.html'}
)

オートコンプリート

別の、でもより複雑なオプションは入力をオートコンプリートウィジェットに置き換えることで、必要に応じて利用可能なオプションの一部のみを読み込み、レンダリングします。これを行う必要がある場合、カスタムオートコンプリートHTMLテンプレートを自分で作成する必要があります。

さまざまなオートコンプリートウィジェット用のパッケージがあり、django-autocomplete-lightなどが含まれます。これらのコンポーネントを標準ウィジェット`として単純に含めることはできませんが、HTMLテンプレートを明示的に記述する必要があります。これは、RESTフレームワーク3.0はテンプレートされたHTML生成を使用するため、`widget`キーワード引数がサポートされなくなったためです。