Flask Mega-Tutorial、パートXXIII：アプリケーションプログラミングインターフェイス（API）

（2018年版）

ミゲル・グリンバーグ

ここに 戻る

これは、Mega-Tutorialの23番目の部分です。アプリケーションプログラミングインターフェイス（またはAPI）を使用して、マイクロブログを拡張する方法を説明します。

ネタバレの下には、2018年シリーズのすべての記事のリストがあります。

注1：このコースの古いバージョンをお探しの場合は、こちらをご覧ください 。

このアプリケーション用にこれまでに作成したすべての機能は、Webブラウザという特定の種類のクライアント向けに設計されています。 しかし、他のタイプの顧客はどうでしょうか？ たとえば、AndroidまたはiOS用のアプリケーションを作成する場合、主に2つの解決方法があります。 最も簡単な解決策は、画面全体を埋めてMicroblog WebサイトをロードするWebコンポーネントを使用してアプリケーションを作成することですが、これはデバイスのWebブラウザーでアプリケーションを開くことより質的には良くありません。 より優れたソリューション（はるかに時間がかかります）は独自のアプリケーションを作成することですが、このアプリケーションはHTMLページのみを返すサーバーとどのようにやり取りできますか？

これは、 アプリケーションプログラミングインターフェイス （またはAPI）が役立つ問題領域です。 APIは、アプリケーションへの低レベルのエントリポイントとして設計されたHTTPルートのコレクションです。 ルートを定義し、Webブラウザーで使用されるHTMLを返す関数を表示する代わりに、APIを使用すると、クライアントはアプリケーションリソースを直接操作して、ユーザーに情報を完全にクライアントに提示する方法を決定できます。 たとえば、マイクロブログのAPIは、クライアントにユーザー情報とブログエントリを提供し、ユーザーが既存のブログエントリを編集できるようにしますが、このロジックをHTMLと混合することなく、データレベルでのみ可能です。

アプリケーションで現在定義されているすべてのルートを調べると、上記で使用したAPI定義に一致するものがいくつかあることに気付くでしょう。 それらを見つけましたか？ 第14章で定義されている/ translateルートなど、JSONを返すいくつかのルートについて説明しています。 これは、 POSTリクエストでテキスト、ソース言語、および宛先言語、すべてのデータをJSON形式で受け入れるルートです。 この要求に対する応答は、このテキストの翻訳であり、JSON形式でもあります。 サーバーは要求された情報のみを返し、クライアントにはこの情報をユーザーに提示する責任があります。

アプリケーションのJSONルートには「フィール」APIがありますが、ブラウザーで実行されるWebアプリケーションをサポートするように設計されています。
アプリケーション内のJSONルートにはAPIがありますが、「感覚」は、ブラウザーで実行されるWebアプリケーションをサポートするように設計されていることです。 スマートフォンアプリケーションがこれらのルートを使用したい場合、登録されたユーザーが必要であり、ログインはHTMLフォームを介してのみ可能であるため、使用できないことに注意してください。 この章では、Webブラウザーに依存しないAPIを作成する方法を説明し、どのクライアントがそれらに接続するかを仮定しません。

この章のGitHubリンク： Browse 、 Zip 、 Diff 。

API設計の基礎としてのREST

誰かが上記の私の声明に強く反対するかもしれません/その翻訳と他のJSONルートはAPIルートです。 他の人は、それらが不十分に設計されたAPIであると考えるという警告に同意するかもしれません。 では、適切に設計されたAPIの特徴は何ですか？また、JSONルートがこのカテゴリ外にあるのはなぜですか？

REST APIという用語を聞いたことがあるかもしれません。 RESTは、Representational State Transferの略で、Roy Fielding博士が博士論文で提案したアーキテクチャです。 フィールディング博士は、RESTの6つの特徴をかなり抽象的かつ一般的な方法で示しています。

フィールディング博士の論文とは別に、他の信頼できるREST仕様はなく、読者に自由に解釈させる余地があります。 与えられたREST APIが一貫しているかどうかのトピックは、REST APIが6つのすべての特性を順守し、RESTの「プラグマティスト」と比較して明確に行う必要があると信じるREST「純粋主義者」の間の激しい議論の源です。フィールディング博士の論文でガイドラインまたは推奨事項として提示されたアイデア。 フィールディング博士自身が純粋主義者陣営の味方であり、ブログとオンラインの解説についての彼のビジョンにいくつかの追加の洞察を与えました。

現在実装されているAPIの大部分は、「実用的な」REST実装に準拠しています。 これには、Facebook、GitHub、Twitterなどの「ビッグプレーヤー」のほとんどのAPIが含まれます。 ほとんどのAPIは純粋主義者が必須と考える実装の詳細をスキップするため、純粋なRESTと満場一致で考えられるパブリックAPIはほとんどありません。 Dr. Fieldingや他のRESTの純粋主義者はREST APIがそうであるかそうでないという厳格な見解にもかかわらず、ソフトウェア業界は通常、実用的な意味でRESTに言及しています。

REST論文の内容を理解するために、以下のセクションでは、フィールディング博士がリストした6つの原則について説明します。

クライアントサーバー

クライアントとサーバーの原則は非常に単純です。RESTAPIでは、クライアントとサーバーの役割を明確に区別する必要があることを示しているだけです。 実際には、これは、クライアントとサーバーがトランスポートを介して相互作用する別個のプロセスにあることを意味します。ほとんどの場合、これはTCPネットワーク上のHTTPプロトコルです。

階層化システム

階層化システム（ マルチレベルシステム ）の原理では、クライアントがサーバーと対話する必要がある場合、実際のサーバーではなく、仲介者に接続できます。 アイデアは、クライアントがサーバーに直接接続されていない場合、クライアントが要求を送信する方法にまったく違いはないということです。実際、ターゲットサーバーに接続されているかどうかさえわからない場合もあります。 同様に、この原則では、サーバーはクライアントから直接ではなく、仲介者からクライアント要求を受信できるため、接続の反対側がクライアントであると想定してはなりません。

これは重要なREST機能です。中間ノードを追加できるため、アプリケーションアーキテクトはロードバランサー、キャッシュ、プロキシなどを使用して大量の要求を満たすことができる大規模で複雑なネットワークを開発できます。

キャッシュ

この原則は、サーバーまたはブローカーがシステムパフォーマンスを向上させるために頻繁に受信される要求に対する応答をキャッシュできることを明示的に示すことにより、階層型システムを拡張します。 おそらくおなじみのキャッシュ実装があります。すべてのWebブラウザーに1つあります。 Webブラウザーのキャッシュレイヤーは、画像などの同じファイルを何度も要求することを避けるためによく使用されます。

APIの目的のために、ターゲットサーバーは、キャッシュ制御の助けを借りて、応答がクライアントに返されるときに仲介者が応答をキャッシュできるかどうかを示す必要があります。 セキュリティ上の理由から、実稼働環境にデプロイされたAPIは暗号化を使用する必要があるため、通常、ホストがSSL接続を終了するか復号化および再暗号化しない限り、キャッシングは中間ホストで実行されません。

オンデマンドのコード

これは、サーバーがクライアントへの応答で実行可能コードを提供できることを示すオプションの要件です。 この原則では、クライアントが実行可能な実行可能コードについてサーバーとクライアント間の合意が必要であるため、これはAPIでほとんど使用されません。 サーバーがWebブラウザーを実行するためにJavaScriptコードを返すと思うかもしれませんが、RESTはWebブラウザークライアント専用に設計されていません。 たとえば、クライアントがiOSまたはAndroidデバイスの場合、JavaScriptの実行はより複雑になる可能性があります。

ステートレス

ステートレスの原則は、RESTの純粋主義者と実用主義者の間のほとんどの議論の中心にある2つのうちの1つです。 REST APIは、このクライアントがリクエストを送信するたびに呼び出されるクライアントの状態を保存すべきではないと述べています。 これは、アプリケーションのページをナビゲートするときにユーザーを「記憶」するWeb開発で一般的なメカニズムは使用できないことを意味します。 ステートレスAPIでは、各リクエストに、サーバーがクライアントを識別および認証し、リクエストを完了する必要がある情報を含める必要があります。 また、サーバーはクライアント接続に関連するデータをデータベースまたはその他の形式のストレージに保存できないことも意味します。

なぜRESTがステートレスサーバーを必要とするのか疑問に思っている場合、主な理由は、ステートレスサーバーのスケーリングが非常に簡単で、ロードバランサーの背後で複数のサーバーインスタンスを起動するだけでよいことです。 サーバーがクライアントの状態を保存する場合、複数のサーバーがこの状態にアクセスして更新する方法を調べる必要があるため、またはこのクライアントが常にスティッキーセッションと呼ばれる同じサーバーによって常に処理されるようにする必要があるため、状況はより複雑になります。

章の冒頭で説明した/翻訳ルートをもう一度見ると、このルートに関連付けられたビュー関数はFlask-Loginの@login_requiredデコーダーに依存しているため、RESTfulとは見なされないことが@login_requiredます。 Flaskユーザーセッションのユーザー状態。

統一されたインターフェース

最後に、最も重要で、最も議論され、最も曖昧に文書化されたREST原則は、単一のインターフェースです。 フィールディング博士は、単一のRESTインターフェースの4つの特徴的な側面を列挙しています：ユニークなリソース識別子、リソース表現、自己記述メッセージ、ハイパーメディア。

一意のリソース識別子は、一意のURLを各リソースに割り当てることによって取得されます。 たとえば、このユーザーに関連付けられているURLは、/ api / users / <user-id>です。ここで、<user-id>は、データベーステーブルのプライマリキーとしてユーザーに割り当てられた識別子です。 これはほとんどのAPIで完全に受け入れられます。

リソース表現の使用は、サーバーとクライアントがリソースに関する情報を交換する場合、一貫した形式を使用する必要があることを意味します。 最近のほとんどのAPIでは、JSON形式を使用してリソース表現を構築します。 APIは、リソースを表すためのいくつかの形式をサポートできます。この場合、HTTPプロトコルのコンテンツネゴシエーションパラメーターは、クライアントとサーバーが両方のユーザーが好む形式をネゴシエートできるメカニズムです。

自己記述メッセージは、クライアントとサーバー間で交換される要求と応答に、相手が必要とするすべての情報を含める必要があることを意味します。 典型的な例は、クライアントがサーバーから受信したい操作を示すために使用されるHTTP要求メソッドです。 GETは、クライアントがリソースに関する情報を取得したいことを示し、 POST要求はクライアントが新しいリソースを作成したいことを示し、 PUTまたはPATCH要求は既存のリソースへの変更を決定し、 DELETE要求はリソースの削除を示します。 ターゲットリソースは、HTTPヘッダー、URLのリクエスト文字列の一部、またはリクエスト本文で提供される追加情報とともに、リクエストURLとして指定されます。

ハイパーメディアの要件は、多くの物議を醸すものであり、少数のAPIで実装されているものであり、それを実装するAPIは、RESTの純粋主義者を満足させるためにめったにそうしません。 アプリケーション内のすべてのリソースが相互接続されているため、リソースビューにリンクを含める必要があります。これにより、顧客がリンクをトラバースして新しいリソースを見つけることができます。もう一つ。 クライアントは、リソースを事前に知らなくてもAPIにアクセスし、ハイパーメディアリンクをたどるだけでAPIについて知ることができます。 この要件の実装を複雑にする側面の1つは、HTMLやXMLとは異なり、通常APIでリソースを表すために使用されるjson形式では、リンクを含める標準的な方法が定義されていないため、特別なカスタム構造、またはJSON-API 、 HAL 、 JSON-LDなど、このギャップを埋めようとする提案されたJSON拡張の

ブループリントAPIコンセプトの実装

APIの開発に関係するもののアイデアを提供するために、マイクロブログに追加します。 これは完全なAPIではありません。ユーザーに関連するすべての機能を実装し、読者へのブログ投稿など、他のリソースの実装は演習として残します。

第15章で説明した概念に従ってすべてが編成および構造化されるように、すべてのAPIルートを含む新しいプロジェクトを作成します。 それでは、このプロジェクトが存在するディレクトリを作成することから始めましょう。

 (venv) $ mkdir app/api 

ブループリント__init __. pyファイル__init __. py __init __. pyは、他のブループリントアプリケーションと同様のブループリントオブジェクトを作成します。

app/api/__init__.py: constructor API。

 from flask import Blueprint bp = Blueprint('api', __name__) from app.api import users, errors, tokens 

循環依存エラーを回避するために、インポートをモジュールの一番下に移動する必要がある場合があることをおそらく覚えているでしょう。 これがapp / api / users.py 、 app / api / errors.pyおよびapp / api / tokens.pyモジュール（これはまだ書いていません）がプロジェクトの作成後にインポートされる理由です 。

APIのメインコンテンツはapp / api / users.pyモジュールに保存されます 。 次の表に、実装するルートを示します。

これらすべてのルートのプレースホルダーを含むモジュールフレームワークは次のようになります。

app/api/users.py:ユーザーAPIリソースプレースホルダー。

 from app.api import bp @bp.route('/users/<int:id>', methods=['GET']) def get_user(id): pass @bp.route('/users', methods=['GET']) def get_users(): pass @bp.route('/users/<int:id>/followers', methods=['GET']) def get_followers(id): pass @bp.route('/users/<int:id>/followed', methods=['GET']) def get_followed(id): pass @bp.route('/users', methods=['POST']) def create_user(): pass @bp.route('/users/<int:id>', methods=['PUT']) def update_user(id): pass 

app / api / errors.pyモジュールでは、エラー応答を処理するいくつかのヘルパー関数を定義する必要があります。 しかし、今、後で入力するプレースホルダーを作成します。

app/api/errors.py:プレースホルダーの処理エラー。

 def bad_request(): pass 

認証サブシステムが定義されるapp / api / tokens.pyモジュール。 これにより、Webブラウザーではないクライアントに代替ログイン方法が提供されます。 このモジュールのプレースホルダーも書きましょう：

app/api/tokens.py:マーカーを処理します。

 def get_token(): pass def revoke_token(): pass 

新しいBlueprint APIスキーマは、アプリケーションファクトリ関数に登録する必要があります。

app/__init__.py:要素図をアプリケーションに登録します。

 # ... def create_app(config_class=Config): app = Flask(__name__) # ... from app.api import bp as api_bp app.register_blueprint(api_bp, url_prefix='/api') # ... 

JSONオブジェクトの形式でのユーザーの表現

APIを実装するときに考慮する最初の側面は、リソースのプレゼンテーションを決定することです。 ユーザーと連携するAPIを実装するため、ユーザーリソースのビューを解決する必要があります。 いくつかのブレーンストーミングの後、次のjsonビューを思いつきました。

 { "id": 123, "username": "susan", "password": "my-password", "email": "susan@example.com", "last_seen": "2017-10-20T15:04:27Z", "about_me": "Hello, my name is Susan!", "post_count": 7, "follower_count": 35, "followed_count": 21, "_links": { "self": "/api/users/123", "followers": "/api/users/123/followers", "followed": "/api/users/123/followed", "avatar": "https://www.gravatar.com/avatar/..." } } 

フィールドの多くは、ユーザーデータベースモデルから直接取得されます。 passwordフィールドは、新しいユーザーを登録するときにのみ使用されるという点で異なります。 第5章でおわかりのように、ユーザーパスワードはデータベースに保存されず、ハッシュのみが保存されるため、パスワードが返されることはありません。 ユーザーのメールアドレスを公開したくないので、 emailフィールドも特別に処理されます。 電子メールフィールドは、ユーザーが自分のエントリを要求した場合にのみ返されますが、他のユーザーからエントリを受信した場合は返されません。 フィールドpost_count 、 follower_countおよびfollow_countは、データベース内のフィールドとしては存在しないが、便宜上クライアントに提供される「仮想」フィールドです。 これは素晴らしい例であり、リソースの表示は、実際のリソースがサーバー上で定義されている方法と一致する必要がないことを示しています。

ハイパー_links要件を実装する_linksセクションを_linksください。 特定のリンクには、現在のリソースへのリンク、そのユーザーをフォローしているユーザーのリスト、ユーザーがフォローしているユーザーのリスト、最後にユーザーのアバター画像へのリンクが含まれます。 将来、このAPIにメッセージを追加することにした場合、ユーザーメッセージのリストへのリンクもここに含める必要があります。

JSON形式の優れた点の1つは、常にPython辞書またはリストビューとして変換されることです。 Python標準ライブラリのjsonパッケージは、Pythonデータ構造とJSONの変換を処理します。 したがって、これらのビューを生成するために、Python辞書を返すto_dict()というUserモデルにメソッドを追加します。

app/models.py:ビューのユーザーモデル。

 from flask import url_for # ... class User(UserMixin, db.Model): # ... def to_dict(self, include_email=False): data = { 'id': self.id, 'username': self.username, 'last_seen': self.last_seen.isoformat() + 'Z', 'about_me': self.about_me, 'post_count': self.posts.count(), 'follower_count': self.followers.count(), 'followed_count': self.followed.count(), '_links': { 'self': url_for('api.get_user', id=self.id), 'followers': url_for('api.get_followers', id=self.id), 'followed': url_for('api.get_followed', id=self.id), 'avatar': self.avatar(128) } } if include_email: data['email'] = self.email return data 

この方法は特別な質問を引き起こすものではなく、基本的に明確にする必要があります。 停止したユーザービューのディクショナリが生成されて返されます。 上で述べたように、ユーザーが自分のデータを要求したときにのみメールを有効にしたいので、 emailフィールドには特別な処理が必要です。 したがって、 include_emailフラグを使用して、このフィールドがビューに含まれているかどうかを判断しinclude_email 。

last_seenフィールドがどのようにlast_seenかに注目してlast_seen 。 日付と時刻のフィールドには、 ISO 8601形式を使用しますisoformat()はisoformat()メソッドを使用して生成できます。 しかし、UTCであるが状態に記録されたタイムゾーンを持たない単純なdatetimeオブジェクトを使用するため、UTCのISO 8601タイムゾーンコードであるZを最後に追加する必要があります。

amkkoからの説明： pythonでは、datetimeオブジェクトはタイムゾーンに関して「単純」または「単純/認識」になります。

最後に、ハイパーメディアリンクの実装方法を確認します。 他のアプリケーションルートを指す3つのリンクの場合、 url_for()を使用してURL（現在app / api / users.pyで定義されている置換要素のルックアップ関数を指しますurl_for()を生成します。 アバターリンクは、アプリケーションの外部のGravatar URLであるため、特別です。 avatar() , -.

to_dict() Python, JSON. , , User . from_dict() , Python :

app/models.py: .

 class User(UserMixin, db.Model): # ... def from_dict(self, data, new_user=False): for field in ['username', 'email', 'about_me']: if field in data: setattr(self, field, data[field]) if new_user and 'password' in data: self.set_password(data['password']) 

, : username , email about_me . , data , , setattr() Python, .

password , . new_user , , , . password , set_password() , .

, API . , , , . :

 { "items": [ { ... user resource ... }, { ... user resource ... }, ... ], "_meta": { "page": 1, "per_page": 10, "total_pages": 20, "total_items": 195 }, "_links": { "self": "http://localhost:5000/api/users?page=1", "next": "http://localhost:5000/api/users?page=2", "prev": null } } 

items - , , . _meta , . _links , , , .

- , , , , API , , . 16 , , , . , , , SearchableMixin , , . , mixin, PaginatedAPIMixin :

app/models.py: mixin.

 class PaginatedAPIMixin(object): @staticmethod def to_collection_dict(query, page, per_page, endpoint, **kwargs): resources = query.paginate(page, per_page, False) data = { 'items': [item.to_dict() for item in resources.items], '_meta': { 'page': page, 'per_page': per_page, 'total_pages': resources.pages, 'total_items': resources.total }, '_links': { 'self': url_for(endpoint, page=page, per_page=per_page, **kwargs), 'next': url_for(endpoint, page=page + 1, per_page=per_page, **kwargs) if resources.has_next else None, 'prev': url_for(endpoint, page=page - 1, per_page=per_page, **kwargs) if resources.has_prev else None } } return data 

to_collection_dict() , items , _meta _links . , , . - Flask-SQLAlchemy, . , . paginate() , , , -.

, . , , , url_for ('api.get_users', id = id, page = page) . url_for() , , url_for() . , kwargs url_for() . page per_page , API.

mixin User :

app/models.py: PaginatedAPIMixin .

 class User(PaginatedAPIMixin, UserMixin, db.Model): # ... 

, , .

エラー処理

, 7 , , , -. API , « » , , . API JSON, API. , :

 { "error": "short error description", "message": "error message (optional)" } 

HTTP . , error_response() app/api/errors.py :

app/api/errors.py: .

 from flask import jsonify from werkzeug.http import HTTP_STATUS_CODES def error_response(status_code, message=None): payload = {'error': HTTP_STATUS_CODES.get(status_code, 'Unknown error')} if message: payload['message'] = message response = jsonify(payload) response.status_code = status_code return response 

HTTP_STATUS_CODES Werkzeug ( Flask), HTTP. error , . jsonify() Response Flask 200, .

, API , 400, " ". -, , , . , , . bad_request() , :

app/api/errors.py: .

 # ... def bad_request(message): return error_response(400, message) 

, JSON, , API.

, id :

app/api/users.py: .

 from flask import jsonify from app.models import User @bp.route('/users/<int:id>', methods=['GET']) def get_user(id): return jsonify(User.query.get_or_404(id).to_dict()) 

view URL-. get_or_404() get() , , , , , None , id , 404 . get_or_404() get() , , .

to_dict() , User , , Flask jsonify() JSON .

, API, , URL- :

 http://localhost:5000/api/users/1 

, JSON. id , , get_or_404() SQLAlchemy 404 ( , , JSON).

, HTTPie , HTTP- , Python, API:

 (venv) $ pip install httpie 

1 (, , ) :

 (venv) $ http GET http://localhost:5000/api/users/1 HTTP/1.0 200 OK Content-Length: 457 Content-Type: application/json Date: Mon, 27 Nov 2017 20:19:01 GMT Server: Werkzeug/0.12.2 Python/3.6.3 { "_links": { "avatar": "https://www.gravatar.com/avatar/993c...2724?d=identicon&s=128", "followed": "/api/users/1/followed", "followers": "/api/users/1/followers", "self": "/api/users/1" }, "about_me": "Hello! I'm the author of the Flask Mega-Tutorial.", "followed_count": 0, "follower_count": 1, "id": 1, "last_seen": "2017-11-26T07:40:52.942865Z", "post_count": 10, "username": "miguel" } 

, to_collection_dict() PaginatedAPIMixin:

app/api/users.py: .

 from flask import request @bp.route('/users', methods=['GET']) def get_users(): page = request.args.get('page', 1, type=int) per_page = min(request.args.get('per_page', 10, type=int), 100) data = User.to_collection_dict(User.query, page, per_page, 'api.get_users') return jsonify(data) 

page per_page , 1 10 , . per_page , 100. , . page per_page to_collection_query() , User.query - , . - api.get_users , , .

HTTPie, :

 (venv) $ http GET http://localhost:5000/api/users The next two endpoints are the ones that return the follower and followed users. These are fairly similar to the one above: app/api/users.py: Return followers and followed users. @bp.route('/users/<int:id>/followers', methods=['GET']) def get_followers(id): user = User.query.get_or_404(id) page = request.args.get('page', 1, type=int) per_page = min(request.args.get('per_page', 10, type=int), 100) data = User.to_collection_dict(user.followers, page, per_page, 'api.get_followers', id=id) return jsonify(data) @bp.route('/users/<int:id>/followed', methods=['GET']) def get_followed(id): user = User.query.get_or_404(id) page = request.args.get('page', 1, type=int) per_page = min(request.args.get('per_page', 10, type=int), 100) data = User.to_collection_dict(user.followed, page, per_page, 'api.get_followed', id=id) return jsonify(data) 

, id . , user.followers user.followed to_collection_dict() , , , , . to_collection_dict() — , kwargs , url_for() .

, HTTPie :

 (venv) $ http GET http://localhost:5000/api/users/1/followers (venv) $ http GET http://localhost:5000/api/users/1/followed 

, hypermedia URL-, _links .

POST /users . :

app/api/users.py: .

 from flask import url_for from app import db from app.api.errors import bad_request @bp.route('/users', methods=['POST']) def create_user(): data = request.get_json() or {} if 'username' not in data or 'email' not in data or 'password' not in data: return bad_request('must include username, email and password fields') if User.query.filter_by(username=data['username']).first(): return bad_request('please use a different username') if User.query.filter_by(email=data['email']).first(): return bad_request('please use a different email address') user = User() user.from_dict(data, new_user=True) db.session.add(user) db.session.commit() response = jsonify(user.to_dict()) response.status_code = 201 response.headers['Location'] = url_for('api.get_user', id=user.id) return response 

JSON , . Flask request.get_json() , JSON Python. None , JSON , , , request.get_json() {} .

, , , , . username , email password . - , bad_request() app/api/errors.py . , username email , , - , .

, , . from_dict() . new_user True , password , .

, , , to_dict() . POST , , 201 , , . , HTTP , 201 Location, URL- .

, HTTPie:

 (venv) $ http POST http://localhost:5000/api/users username=alice password=dog \ email=alice@example.com "about_me=Hello, my name is Alice!" 

, API, — , :

app/api/users.py: .

 @bp.route('/users/<int:id>', methods=['PUT']) def update_user(id): user = User.query.get_or_404(id) data = request.get_json() or {} if 'username' in data and data['username'] != user.username and \ User.query.filter_by(username=data['username']).first(): return bad_request('please use a different username') if 'email' in data and data['email'] != user.email and \ User.query.filter_by(email=data['email']).first(): return bad_request('please use a different email address') user.from_dict(data, new_user=False) db.session.commit() return jsonify(user.to_dict()) 

id URL, 404 , . , , username email , , , , . , , , . , , , , , , . - , 400 , .

From_dict() , , . 200 .

, about_me HTTPie:

 (venv) $ http PUT http://localhost:5000/api/users/2 "about_me=Hi, I am Miguel" 

API

API, , . , , , «AuthN» «AuthZ» . , , , , , , , .

API @login_required Flask-Login, . , HTML . API HTML , , , 401. , API - HTML. API 401, , , , .

()

API . API, , . API, , , . . User :

app/models.py: .

 import base64 from datetime import datetime, timedelta import os class User(UserMixin, PaginatedAPIMixin, db.Model): # ... token = db.Column(db.String(32), index=True, unique=True) token_expiration = db.Column(db.DateTime) # ... def get_token(self, expires_in=3600): now = datetime.utcnow() if self.token and self.token_expiration > now + timedelta(seconds=60): return self.token self.token = base64.b64encode(os.urandom(24)).decode('utf-8') self.token_expiration = now + timedelta(seconds=expires_in) db.session.add(self) return self.token def revoke_token(self): self.token_expiration = datetime.utcnow() - timedelta(seconds=1) @staticmethod def check_token(token): user = User.query.filter_by(token=token).first() if user is None or user.token_expiration < datetime.utcnow(): return None return user 

token , , . token_expiration , . , , .

. get_token() . , base64, . , , .

, . , . revoke_token() , , , .

check_token() , , . , None.

, , :

 (venv) $ flask db migrate -m "user tokens" (venv) $ flask db upgrade 

()

API, , -, -. API , , . API, , -.

, Flask Flask-HTTPAuth . Flask-HTTPAuth pip:

 (venv) $ pip install flask-httpauth 

Flask-HTTPAuth , API . HTTP Basic Authentication 11.1 , http . Flask-HTTPAuth : , , , , . Flask-HTTPAuth , . :

app/api/auth.py: .

 from flask import g from flask_httpauth import HTTPBasicAuth from app.models import User from app.api.errors import error_response basic_auth = HTTPBasicAuth() @basic_auth.verify_password def verify_password(username, password): user = User.query.filter_by(username=username).first() if user is None: return False g.current_user = user return user.check_password(password) @basic_auth.error_handler def basic_auth_error(): return error_response(401) 

HTTPBasicAuth Flask-HTTPAuth- , . verify_password error_handler .

, , True , , False , . check_password() User , Flask-Login -. g.current_user , API.

401, error_response() app/api/errors.py . 401 HTTP "Unauthorized" (" "). HTTP , .

, , , :

app/api/tokens.py: Generate user tokens.

 from flask import jsonify, g from app import db from app.api import bp from app.api.auth import basic_auth @bp.route('/tokens', methods=['POST']) @basic_auth.login_required def get_token(): token = g.current_user.get_token() db.session.commit() return jsonify({'token': token}) 

@basic_auth.login_required HTTPBasicAuth, Flask-HTTPAuth ( ) , . get_token() . , , .

POST API :

 (venv) $ http POST http://localhost:5000/api/tokens HTTP/1.0 401 UNAUTHORIZED Content-Length: 30 Content-Type: application/json Date: Mon, 27 Nov 2017 20:01:00 GMT Server: Werkzeug/0.12.2 Python/3.6.3 WWW-Authenticate: Basic realm="Authentication Required" { "error": "Unauthorized" } 

HTTP 401 , basic_auth_error() . , :

 (venv) $ http --auth <username>:<password> POST http://localhost:5000/api/tokens HTTP/1.0 200 OK Content-Length: 50 Content-Type: application/json Date: Mon, 27 Nov 2017 20:01:22 GMT Server: Werkzeug/0.12.2 Python/3.6.3 { "token": "pC1Nu9wwyNt8VCj1trWilFdFI276AcbS" } 

200, , . , <username>:<password> . .

API

API, . , Flask-HTTPAuth . HTTPTokenAuth :

app/api/auth.py: Token.

 # ... from flask_httpauth import HTTPTokenAuth # ... token_auth = HTTPTokenAuth() # ... @token_auth.verify_token def verify_token(token): g.current_user = User.check_token(token) if token else None return g.current_user is not None @token_auth.error_handler def token_auth_error(): return error_response(401) 

Flask-HTTPAuth verify_token , , . User.check_token() , , . , None . True False , Flask-HTTPAuth .

API , @token_auth.login_required :

app/api/users.py: Protect user routes with token authentication.

 from app.api.auth import token_auth @bp.route('/users/<int:id>', methods=['GET']) @token_auth.login_required def get_user(id): # ... @bp.route('/users', methods=['GET']) @token_auth.login_required def get_users(): # ... @bp.route('/users/<int:id>/followers', methods=['GET']) @token_auth.login_required def get_followers(id): # ... @bp.route('/users/<int:id>/followed', methods=['GET']) @token_auth.login_required def get_followed(id): # ... @bp.route('/users', methods=['POST']) def create_user(): # ... @bp.route('/users/<int:id>', methods=['PUT']) @token_auth.login_required def update_user(id): # ... 

, API, create_user() , , , , .

, , 401. , Authorization , /api/tokens . Flask-HTTPAuth , -, HTTPie. HTTPie --auth , . -:

 (venv) $ http GET http://localhost:5000/api/users/1 \ "Authorization:Bearer pC1Nu9wwyNt8VCj1trWilFdFI276AcbS" 

, , , — , :

app/api/tokens.py: Revoke tokens.

 from app.api.auth import token_auth @bp.route('/tokens', methods=['DELETE']) @token_auth.login_required def revoke_token(): g.current_user.revoke_token() db.session.commit() return '', 204 

DELETE URL- /tokens , . , , Authorization , . User , . , . , . return 204, , .

, HTTPie:

 (venv) $ http DELETE http://localhost:5000/api/tokens \ Authorization:"Bearer pC1Nu9wwyNt8VCj1trWilFdFI276AcbS" 

API

, , API URL- ? 404, 404 HTML. , API, JSON API, , Flask, - , , HTML.

HTTP , , . Accept , . , , , .

, HTML JSON . Flask request.accept_mimetypes :

app/errors/handlers.py: .

 from flask import render_template, request from app import db from app.errors import bp from app.api.errors import error_response as api_error_response def wants_json_response(): return request.accept_mimetypes['application/json'] >= \ request.accept_mimetypes['text/html'] @bp.app_errorhandler(404) def not_found_error(error): if wants_json_response(): return api_error_response(404) return render_template('errors/404.html'), 404 @bp.app_errorhandler(500) def internal_error(error): db.session.rollback() if wants_json_response(): return api_error_response(500) return render_template('errors/500.html'), 500 

ヘルパー関数wants_json_response()は、優先形式のリストでクライアントが選択したJSONまたはHTMLの設定を比較します。JSONの速度がHTMLよりも速い場合、JSON応答を返します。それ以外の場合、元のテンプレートベースのHTML応答を返します。JSONの回答についてerror_responseは、API要素のスキーマからヘルパー関数をインポートしますが、ここで名前を変更してapi_error_response()、その機能と生成元が明確になるようにします。