イントロダクション

2020年2月頃より進めてきたプロジェクトがようやく一区切りつきそうなので、使用した技術について振り返りも含めたリンク集となります。
プロジェクト内での役割的には、ほぼ要件定義メンバー兼任のプロジェクトマネージャーでプロジェクト終盤に実装も手伝ったという形となります。
そのため実装メインで関わっていたわけではないので、以下「Django Rest Framework」に関する理解が不十分な点があるかもしれませんが、何らか役立つような情報が記載できればと思います。

リンク集

Django REST framework 実践入門

2018/5/19公開の資料なので2020/08/02現在では、もしかしたら内容的には若干最新ではないかもしれませんが、以下についてまとめられています。

Serializer
- serializers.Serializer
- serializers.ModelSerializer
- serializers.ListSerializer
- serializers.HyperlinkedModelSerializer
Renderer / Parser
Router
API documentation
Profiling

個人的には、すでにDjangoでのWebアプリ作成経験があり、その上でREST frameworkについてもキャッチアップしようとしている方向けの資料かと感じました。DjangoのModel定義など前提事項となる知識があった上で読まれる場合は、すんなりと頭に入るかと思います。

サンプルコードの記載もあり、各Serializerの特徴も掴みやすいですし、経験値に基づく課題の解消などの記載もあり、改めて振り返るにあたってためになりました。

Command-Query分離やsnake_case <=> camelCaseの変換などは、今回、自分の関わったプロジェクトでも出てきた課題だったので、多くの方が通る道なのかなと思います。

Routerについては、今回のアプリケーションの仕様上、RESTfulなエンドポイントが最適ではなかったので、採用していませんでした。

Django REST Framework の使い方メモ

Djangoプロジェクトの作成から記載があり、まったくの初心者の方でも手を動かしながら順を追って理解ができる流れになっています。おおまかにDjangoでの簡単なサンプルアプリケーション作成から入り、「Django REST Framework」のライブラリ追加、API実装という流れになっており、そもそもDjango自体に馴染みがない方におすすめです。

SPAのバックエンドを「Django REST Framework」で作る際に１つ課題となるcorsについても、対応方法の記載があります。また、今回、自分の関わったプロジェクトでは、外部の認証サービスを利用していることもあり、採用していませんでしたが、アクセス制御の仕組みついても触れられています。

Serializerは、ModelSerializerのみ使用しており、RESTfulなエンドポイント設計を前提とした記事になっているので、個人的には、シンプルなREST APIバックエンドを開発する際にとても参考になる記事かと思いました。

Django REST Frameworkを使って爆速でAPIを実装する

「そもそもREST APIとは」といった説明もありつつ、基本的なModelSerializerを使用したサンプルコードを記載されています。さらにリレーションモデルの展開やページネーション、フィルターといった「Django REST Framework」の機能も紹介されています。

RESTfulなAPIについての解説がまずあった上で、「Django REST Framework」の機能紹介になっているので、REST APIの開発にあまり馴染みのなかった方でもすんなり頭に入ってきやすい記事になっているのではないかと思いました。

[Django REST Framework] Serializer の使い方をまとめてみた

Djangoの経験者を前提とした記事となっています。まずは、タイトルの通り、Serializerに関する紹介があります。

上記に続いて、

所々、Djangoとの比較コメントがあることによって、Django経験者の方は、「Django REST FrameworkのDjangoとの違い」を意識しながら理解できる点が良いなと感じました。サンプルコードもあってわかりやすいです。

Serializerだけでなく、FieldsやValidationについても取り上げて解説されているので、APIの入力・出力に関わる部分の処理を考える際に、とても参考になるかと思いました。

[Django REST Framework] View の使い方をまとめてみた

記事内に記載がありますが、Djangoの経験者を前提とした記事となっています。まずは、タイトルの通り、Viewに関する紹介があります。

上記に続いて、

の紹介がされています。

Serializerと同様に所々、Djangoとの比較コメントがあることによって、Django経験者の方は、「Django REST FrameworkのDjangoとの違い」を意識しながら理解できる点が良いなと感じました。各カテゴリごとの説明も、そのカテゴリ内で選択肢となりうる要素を列挙して説明されているので、実装方法の検討をする際に、とても参考になるかと思いました。

サンプルコードもあってわかりやすいです。

Build a REST API in 30 minutes with Django REST Framework（英語）

※そのまま英語で読めるほど英語力は高くないのでDeepLのお世話になりながら読みました。

Why REST API?

最初に「そもそもREST APIとは？」というところから始まっており、API開発の初心者にも分かりやすい記事になっています。

Why Django REST Framework?

イントロダクションとして「Django REST Framework」を使うとどういった利点があるのかを簡単に紹介したあと、

Set up Django
Create a model in the database that the Django ORM will manage
Set up the Django REST Framework
Serialize the model from step 2
Create the URI endpoints to view the serialized data

といった流れでそもそもDjangoのセットアップから簡単なAPIの開発を手順を追って解説されています。そのためDjango自体の開発経験がない方でも分かりやすい記事になっています。

serializerについては、「serializers.HyperlinkedModelSerializer」を使用されているので、その点は、他の記事を読んでキャッチアップする必要がある感じです。タイトルにもあるように「30分」ぐらいで簡単なAPIを「Django REST Framework」で作れるといった記事です。

serializerに加えて、viewについても細かい解説はない代わりにコマンドの記載もあり、手順がしっかりしているので「とりあえず動かしてみたい！」といった人向けの内容でした。

Django Rest Framework – An Introduction（英語）

大まかな流れとしては、

DRF Setup

「Django Rest Framework」のセットアップ

RESTful Structure

「REST API」自体の基本的な構造の説明

Model Serializer

Serializerの１つであるModel Serializerについての解説

DRF Web Browseable API

簡易的にHTML・JavaScript・Ajaxで作ったフロントエンドと組み合わせながら、APIを呼び出して表示・操作するサンプル紹介

となっています。

冒頭、「Django Rest Framework」のセットアップから始まっているように、Djangoの経験者を前提としたものになります。ただ、使っているModelもだいぶシンプルなのでDjango Girls のチュートリアルをやった流れでそのままこの記事の流れをやっても理解できる範囲かと思いました。

ほんとにシンプルに「Django Rest Framework」を使って、「REST API」を作るとこんな感じになりますよ、といった感じの記事です。簡易的ながらHTML・JavaScript・Ajaxで作ったフロントエンドもあるので、実際ブラウザから通信させながらバックエンドのAPIを呼びだす、基本的な構成が体験できます。

Django REST framework 公式ドキュメント（英語）

本家本元、公式サイトです。サイト構成的には、

Home
- Funding
  - 開発支援している会社の紹介
- Requirements
  - PythonやDjangoのサポートバージョンや、オプションパッケージについての説明
- Installation
  - すでにDjangoが入っている前提でインストール方法の紹介
- Example
  - 既存のUserモデルを利用したごくごく簡単な一覧取得APIの実装紹介
- Quickstart
  - 以下、Tutorialへの導線
- Development
  - 以下、Communityへの導線
Tutorial
- Project setup
  - djangoおよびDjango REST frameworkのinstallから始まります。
  - djangoのinstallから始まりますが、django自体の説明は省略されているので、流石にDjango Girls のチュートリアルぐらいはやっていないと、やってる作業の意味がわからないかと思います。
- Serializers
  - HyperlinkedModelSerializerを前提として、既存のUserモデル、Groupモデルを用いた簡単なSerializer実装が紹介されています。
  - ここら辺もすでにDjango自体がUserモデル、Groupモデルをデフォルトで持っていることを知っていないと戸惑うかもしれません。
- Views
  - ModelViewSetを前提として、queryset・serializer_class・permission_classesを設定したViews実装を紹介しています。
  - 個々の技術要素については、ここで解説されないので適宜Api Guideを見ながら進める必要がありそうです。
  - 実装自体は、User、Groupそれぞれの認証が必要な一覧取得APIを実装しているものです。
- URLs
  - router使用を前提として自動でURL生成される仕組みの実装紹介がされています。
  - 個々に独自にURL設定できる点も解説で触れられています。
- Pagination
  - Frameworkとしてすでに用意しているPaginationの仕組みの設定紹介です。
  - DEFAULT_PAGINATION_CLASS、PAGE_SIZEの指定について記載があります。
- Settings
  - INSTALLED_APPSへのrest_frameworkの追加記述です。
- Testing our API
  - curlコマンドを使って実際に作ったAPIのレスポンスを確認しています。
  - また、Framework標準で用意しているブラウザからの確認も紹介しています。
  - UserとGroupの一覧取得できることが確認できます。
Api Guide
- Requests
  - frameworkが提供するRequestの各種仕様が紹介されているといった感じです。
  - 基本的なフロントエンドからのリクエストを受け取るrequest.dataから、認証関連のrequest.userなどの説明があります。
  - Request parsing、AuthenticationあたりがバックエンドAPIを作るにあたって参照しておくべきポイントかと思いました。実際、今回の自分のプロジェクトでも使っている部分です。
- Responses
  - frameworkが提供するResponseの各種仕様が紹介されているといった感じです。
  - 基本は、jsonで返すと思うのでそこまでこのドキュメントを読み込んで理解しないといけないものではないかなと思いました。
- Views
  - 基本となるAPIViewをベースとしたClass-based ViewsとFunction Based Viewsについて解説されています。
  - views自体は、MVCモデルで言う所のcontrollerという理解を自分はしているのですが、Django経験者じゃないと馴染みのないワードかと思います。
  - Class-based Viewsの説明の後続に
    - API policy attributes
    - API policy instantiation methods
    - API policy implementation methods
    - Dispatch methods
      - の記載があり、さらに細かく個々のテーマごとの詳細な紹介があります。
  - バックエンドの入り口になる部分なのでプロジェクト初期段階の設計段階では、結構読み込むべき部分かなと思いました。
- Generic views
  - Generic views自体は、APIの仕様に合致したものが使えれば、実装がかなり楽になるものという理解をしていますが、その機能解説がされています。
  - CreateAPIView, ListAPIView, RetrieveAPIView, DestroyAPIView, UpdateAPIView...と数多くのAPIのパターンに応じたviewsが用意されています。
  - ここもプロジェクト初期段階の設計段階では、結構読み込むべき部分かなと思ったのですが、楽に実装できるほど規約に沿わないといけないという経験上の理由からGeneric viewsの利用は、見極めが必要なのかなと思いました。
  - 内容を見る限り、強くREST APIの仕様を意識したものだと思うので、作るエンドポイントの仕様によっては、選択しない方いいということになりそうな気がしました。
  - 実際、今回のプロジェクトでは、結構な本数のAPIが実装されましたが、CreateAPIView、ListAPIView、UpdateAPIViewの利用はごく一部に止まっています。
- ViewSets
  - Django REST framework allows you to combine the logic for a set of related views in a single class, called a ViewSet（Django REST フレームワークでは、ViewSet と呼ばれる単一のクラスに関連するビューのセットのロジックを組み合わせることができます。）と記載があるように、自分の理解では、前段の個別のGeneric viewsの機能を集約したものと見ています。
  - ViewSetが提供するactionとしてもcreate/retrieve/update/destroyとなっており、やはり強くREST APIの仕様を意識したものという印象です。
  - こちら今回のプロジェクトでは、使用していません。
- Routers
  - SimpleRouterとDefaultRouterなどの説明があります。
  - SimpleRouterですが、urlのprefixとviewsetを指定すると、自動でRestfulなurlを定義してくれるものです。
  - 基本的にviewsetの利用を前提とした仕組みのようなので、その点を考慮して適宜参照する部分かと思います。
  - こちら今回のプロジェクトでは、使用していません。
- Parsers
  - フロントエンドからのリクエストを受け取る際のParserについて紹介されています。
  - などContent-Typeに応じたParserが用意されています。
  - 今回のプロジェクトでは、デフォルトのこちらのParserは使わずdjangorestframework-camel-caseをsnake_case <=> camelCase対応のために使用しています。
    - CamelCaseFormParser
    - CamelCaseMultiPartParser
    - CamelCaseJSONParser
- Renderers
  - フロントエンドへレスポンスを返す際のRendererについて紹介されています。
  - などのRendererが用意されています。
  - 今回のプロジェクトでは、デフォルトのこちらのRendererは使わずdjangorestframework-camel-caseをsnake_case <=> camelCase対応のために使用しています。
    - CamelCaseJSONRenderer
    - CamelCaseBrowsableAPIRenderer
- Serializers
  - フロントエンドとのリクエスト・レスポンスのやり取りをする際にシリアライズ・デシリアライズするためのSerializerの紹介がされています。
  - こちらについては、[Django REST Framework] Serializer の使い方をまとめてみたでもだいぶ紹介されているので、英語が苦手な方はそちらをまず読んでから確認された方がいいかもしれません。
  - 今回のプロジェクトでは、serializers.Serializer、serializers.ModelSerializerといった基本的なSerializerのみ使用しています。
- Serializer fields
  - 文字通りSerializerで使えるfieldsの紹介です。
  - 大きく分けて
  - が解説されています。
  - Django経験者であれば、Modelで使えるfieldsと似たり寄ったりなので差分を見ていく形になるかと思います。
- Serializer relations
  - ForeignKey, ManyToManyField, OneToOneFieldなどModelからのリレーション先に対するSerializerの解説がされています。
  - Modelをベースにした仕組みなのでModelSerializerの使用を前提として紹介がされています。
  - 関連モデルも一緒にフロントエンドに返したい時に考慮される仕組みかと思います。
- Validators
  - Most of the time you're dealing with validation in REST framework you'll simply be relying on the default field validation, or writing explicit validation methods on serializer or field classes.(ほとんどの場合、RESTフレームワークでバリデーションを扱う際には、デフォルトのフィールドバリデーションに頼ったり、シリアライザやフィールドクラスに明示的なバリデーションメソッドを書いたりすることになります。)
  - However, sometimes you'll want to place your validation logic into reusable components, so that it can easily be reused throughout your codebase. This can be achieved by using validator functions and validator classes.(しかし、コードベース全体で簡単に再利用できるように、バリデーションロジックを再利用可能なコンポーネントに配置したいと思うこともあるでしょう。これはバリデータ関数やバリデータクラスを使うことで実現できます。)
  - ということで、Frameworkが用意しているvalidatorsの紹介とcustom validatorsの作り方について解説がされています。
  - 結構、似たようなエラーチェック処理をあちこちで書いているので集約したい、といったことは発生しがちだと思うので、そういった際に参照することになると思います。
- Authentication
  - 認証の仕組みの紹介です。
    - BasicAuthentication
    - TokenAuthentication
    - SessionAuthentication
    - RemoteUserAuthentication
    - などFrameworkとして用意しているAuthenticationやCustom authentication、Third party packagesについて解説されています。
- Permissions
  - 認可の仕組みの紹介です。
    - AllowAny
    - IsAuthenticated
    - IsAdminUser
    - IsAuthenticatedOrReadOnly
    - DjangoModelPermissions
    - DjangoModelPermissionsOrAnonReadOnly
    - DjangoObjectPermissions
    - などFrameworkとして用意しているPermissionやCustom permissions、Third party packagesについて解説されています。
- Caching
  - cash機構の紹介です。毎回、アクセスしても変わらないマスタデータなどに使えそうですが、Redisなどと比べるとどうなのかは気になるところです。
- Throttling
  - Throttling is similar to permissions, in that it determines if a request should be authorized. Throttles indicate a temporary state, and are used to control the rate of requests that clients can make to an API.(スロットルはパーミッションに似ていますが、リクエストが許可されるべきかどうかを決定します。スロットルは一時的な状態を示し、クライアントが API に対して行うことができるリクエストの速度を制御するために使用されます。)とあるように、APIのリクエストに対して制限をかけるものです。
  - 例として記載されているものは、１日あたり〇〇回までリクエストを許可する、といった回数制限です。
  - 特定のプロダクト内だけではなく、外部へAPIとして公開する際に利用することになりそうです。
- Filtering
  - Django経験者であれば馴染みのあるfilterですが、generics.ListAPIViewと組み合わせて、検索結果の絞り込みをする仕組みとして紹介がされています。
- Pagination
  - 文字通りページネーションの仕組みの説明がされています。
  - Pagination is only performed automatically if you're using the generic views or viewsets. If you're using a regular APIView, you'll need to call into the pagination API yourself to ensure you return a paginated response. (ページ分割が自動的に実行されるのは、一般的なビューやビューセットを使用している場合のみです。通常の APIView を使用している場合は、ページ分割されたレスポンスを確実に返すために自分でページ分割 API を呼び出す必要があります。)とあるように、基本は、generic views、viewsetsの利用を前提としたものですが、APIViewでも利用できる方法はあるようです。
- Versioning
  - APIのバージョン管理のための仕組みが記載されています。
  - V1, V2, V3...等、API自体のバージョンを指定して呼びだすことが想定される場合に必要になりそうです。
- Content negotiation
  - FrameworkとしてContent negotiationへのサポートを紹介しています。
- Metadata
  - レスポンスにオプションとして追加できるMeta情報の仕組みについての解説です。
  - 一例としてエンドポイントの名前や説明を付与したレスポンスの記載があります。
- Schema
  - OpenAPI Schemaの自動生成など、ここではAPIスキーマについてのサポートが紹介されています。
- Format suffixes
  - Accept headersの代わりに、例えば 'http://example.com/api/users.json' でアクセスされれば、jsonでレスポンスを返すというformat suffixesへのサポートについて紹介されています。
- Returning URLs
  - As a rule, it's probably better practice to return absolute URIs from your Web APIs, such as http://example.com/foobar, rather than returning relative URIs, such as /foobar.(原則として、/foobarのような相対URIを返すよりも、http://example.com/foobarのようなWeb APIから絶対URIを返す方が良いでしょう。)ということで、絶対URIの取得についてのサポートが紹介されています。
- Exceptions
  - 文字通りExceptionの取り扱いについて説明がされています。
  - などFrameworkですでに用意しているExceptionの解説もあります。
- Status Codes
  - 文字通りステータスコードへのFrameworkとしてのサポートが紹介されています。
- Testing
  - 文字通りAPIのテストについてのFrameworkとしてのサポートが紹介されています。
- Settings
  - 割と各セクションごとに触れられていましたが、REST_FRAMEWORKの各種設定についてまとめて記載されています。
Topics
- Documenting your API
  - APIのドキュメンテーションについての解説です。
  - Two popular options are Swagger UI and ReDocということで、SwaggerとReDocの簡単な紹介と設定方法が記載されています。
  - Django Rest Frameworkとしては、デフォルトでAPIの動作確認ができるbrowsable APIも用意されているので、そちらについても少し触れられています。
- API Clients
  - 大きく分けて以下３つのAPI Clientの紹介とチュートリアルが記載されています。個人的には、browsable APIやSwaggerで動作確認をすればいいと思うので、何らか事情があってこれらのAPI Clientを利用する方向けの内容かなと思いました。
- Internationalization
  - リンク切れとなっていたのですが、Django's standard translation mechanisms.を前提とした各種言語への翻訳サポートについて記載があります。
  - おそらくこちらDjango公式のtranslationへのリンクだったのかなと思います。
  - Django自体は日本語のサポートも行っているようなので「ja」で設定すれば、エラーメッセージが日本語化できるのかなと思います。
    - 参考：Django、多言語対応
- Working with AJAX, CSRF & CORS
  - フロントエンド側のAJAXを用いたCSRF & CORSといった技術要素に対するサポート内容が記載されています。
- HTML & Forms
  - Django REST Frameworkでもhtmlテンプレートを使って、APIのレスポンスとしてHTMLとFormに対応していることの紹介です。
  - 個人的には、HTMLをレスポンスとして返すならDjangoをそのまま使えばいいのでは...?という感じがしたのですが、こんなことも出来るよ、という紹介なのかなと思います。
- Browser enhancements
  - 冒頭に「In order to allow the browsable API to function, there are a couple of browser enhancements that REST framework needs to provide. (ブラウズ可能なAPIを機能させるためには、RESTフレームワークが提供しなければならないいくつかのブラウザの機能強化があります。)」と記載があり、ajax-form libraryを用いたform実装の紹介などがあります。
  - 内容を見る限り、formを使ってsubmitする形でRest APIを呼び出したい場合に参照するところなのかなと思いました。
- The Browsable API
  - Django REST Frameworkに元からあるAPI動作確認のための機構の紹介になっています。
  - Swaggerなどを利用する場合には、参照すること必要はなさそうです。
- REST, Hypermedia & HATEOAS
  - Django REST frameworkから派生してHypermedia APIに言及した内容になっています。
    - Hypermedia APIの設計をするならここら辺のサイトを読んだ方がいい、REST frameworkを使ってHypermedia APIを作るには、作るに当たって何が提供されるのか、といった点に言及されています。
    - Hypermedia API自体、自分も知らなかったのですが、リンクされたWorld Wide Webの世界の情報にアクセスするためのAPI...といった感じでしょうか。
      - 参考:What Is Hypermedia?
Community
- Tutorials and Resources
  - 英語ベースですが、
    - 本
    - チュートリアルサイト
    - 動画
    - Django REST Frameworkに関する記事
  - のリンク集になっています。
- Third Party Packages
  - こちらはサードパーティーとしてパッケージを作りたい時はこうしてください、という説明になっています。
- Contributing to REST framework
  - Django REST Frameworkの開発コミュニティに参加するに当たっての注意書きといった内容になっています。
- Project management
  - Django REST Frameworkの開発プロジェクトに関する体制やリリースプロセスが紹介されています。
- あとは、リリースノートなど...etc.

一通り復習してみての感想

どの順番で「Django REST Framework」の理解をしていったら良かったのか。

あまり実装に参加せず、Frameworkの全体像を掴めていなかったので、今回復習もかねて一通り見てみましたが、やはり公式チュートリアルが一番勉強になりました。とはいえ、いきなり公式チュートリアルに挑んでいたら、途中で挫折していたような気もします。

どの順番で「Django REST Framework」の理解をしていったら良かったのか、といったところで考えると、本当に初心者を前提とすると、

少なくともDjangoのチュートリアルをやるなりして、Django自体への理解を深める。
REST APIとはなんだ、ということを調べて理解を深める。
実際に手を動かして簡単なRestfulなCRUDのAPIを作れる「Django REST Framework」のチュートリアルをやってみる。
Reactなり、 HTML x JavaScript x Ajaxでフロントエンドを実装してみて、APIとつなげてみる。
公式チュートリアルを読みながら、実装していない部分を参照しながら実際に実装してみて理解を深める。

といった感じなのかな、と思いました。

名前の通りRestfulなAPIをPythonベースで作るのであれば、機能も豊富で良さそう。

「Django REST Framework」の機能を１つ１つ確認して行く中で、本当に機能が豊富なので、名前の通りRestfulなAPIをPythonベースで作るのであれば使いがいのあるFrameworkだなと感じました。ただ、モデル設計だったりエンドポイントの設計もRESTを意識しないと、その実力を十分に引き出せないだろうというのも事実かなと感じました。

こちらの記事で記載させていただいた通り、最初はRESTを意識せずにモデル設計をし、エンドポイントの設計もしていたので、もしかしたらRESTを意識して設計をやり直せていたら、もっとFramework自体のポテンシャルを引き出せていたのではないかなと思いました。

とはいえ、ビジネスロジックをゴリゴリAPIで実装する場合には、RestfulなAPIで収まるんだろうか。

単純なるモデルを扱うCRUD APIであれば、Generic viewsとModelSerializerとDjango Modelで実装してしまって、URLもSimpleRouterで自動生成という感じで、RestfulなAPI設計で行けると思うのですが、ビジネスロジックをゴリゴリAPIで実装する場合には、結局Service層なりを間に挟む必要があって、そうなるといわゆるRESTの思想からは逸脱したところに行かないといけないのかなーと感じています。

実際、今回のプロジェクトでもシンプルにModelベースで実装しているところとService層をView層の後に入れて実装しているところと分かれています。

最後に

個人的には、要件定義＆マネジメント寄りのポジションで今回のプロジェクトを過ごしていたので、フロントエンド・バックエンド含めて開発メンバーがわいわい設計や実装をしているのが正直羨ましかったと、同時に技術的な経験値を十分に積めてないのではという不安があったのですが、振り返りをすることで少しでも補完できれていれば良いなと考えています。

過去、JavaやC#含めAPI開発向けのFrameworkは経験したことがなかったので、今回復習してみて「なるほど、APIを作るならこういう機能いるよね」という気づきがあってとても良かったです。同時に「Django REST Framework」の機能の豊富さも感心しました。

少しでもこの記事が誰かの役に立てば幸いです。