PythonでAPIを開発するときは、動くエンドポイントを用意するだけでは十分ではありません。APIは、アプリケーションや外部システムがデータをやり取りするための接点です。そのため、リクエストとレスポンスの形、エラー時の返し方、認証・認可、将来の変更方法まで含めて設計しておく必要があります。
最初に決めるべきなのは「どのURLで何を扱うか」だけではありません。APIを使う側と提供する側が共有する約束、つまりAPI契約を整えることが重要です。契約があいまいなまま実装を進めると、フロントエンド、モバイルアプリ、外部連携先との認識違いが起きやすくなり、運用後の修正コストも大きくなります。
この記事では、PythonでAPIを作る際に押さえておきたい基本方針を、フレームワーク選定、REST設計、入力検証、認証・認可、非同期処理、ドキュメント、バージョニングの順に整理します。
まず決めるべきAPI設計の方針
API開発では、実装に入る前に設計の前提をそろえておくと、後からの手戻りを減らせます。特に業務APIでは、誰が使うのか、どのデータを扱うのか、どこまで公開するのかを先に確認しておくことが大切です。
| 確認すること | 決めておく内容 | 後回しにした場合の問題 |
|---|---|---|
| 利用者 | 社内画面、モバイルアプリ、外部システムなど、誰がAPIを使うか | 必要なレスポンス形式や権限設計がぶれやすい |
| データの単位 | ユーザー、注文、記事など、APIで扱うリソースの範囲 | URLやレスポンス構造が場当たり的になりやすい |
| エラー応答 | 入力不備、認証失敗、権限不足、存在しないデータをどう返すか | 利用側が原因を特定しにくくなる |
| 変更方針 | 互換性を保つ範囲、バージョニング、古い仕様の扱い | 既存クライアントを壊す変更につながりやすい |
この段階で完璧な設計書を作る必要はありません。ただし、リソース、認証、エラー、変更方針だけでも言語化しておくと、実装チーム内の判断がそろいやすくなります。
Python API開発で使われる主なフレームワーク
PythonにはAPI開発に使いやすいフレームワークが複数あります。小さく始めたいのか、業務アプリケーション全体を含めて作りたいのか、非同期処理や仕様確認のしやすさを重視するのかによって選び方が変わります。関連する選定観点は、Pythonフレームワークの種類と選び方でも整理しています。
| フレームワーク | 向いている場面 | 設計時の注意点 |
|---|---|---|
| Flask | 小規模API、必要な機能を選びながら構成したいサービス | 認証、入力検証、構成管理などをプロジェクト側で決める必要がある |
| FastAPI | 型ヒント、非同期処理、API仕様の確認しやすさを重視するAPI | 同期処理と非同期処理の境界、データモデルの責務を整理しておく |
| Django REST Framework | Djangoを土台に、管理画面やデータモデルを含む業務アプリケーションへAPIを追加する場合 | Django側のモデル設計、権限管理、シリアライザー設計と一体で考える |
Flask
Flaskは軽量なマイクロフレームワークです。必要最小限の構成から始めやすく、機能を選びながら追加できるため、小規模なAPIや要件が明確なサービスに向いています。一方で、認証、入力検証、構成管理などはプロジェクト側で方針を決めて組み立てる必要があります。
FastAPI
FastAPIは、型ヒントを活かした実装、非同期処理、API仕様の確認しやすさを重視したい場合に使いやすいフレームワークです。高トラフィックを想定するAPIや、フロントエンド・外部システムとの連携が多いAPIでは、リクエストとレスポンスの形を明確にしやすい点がメリットになります。
Django REST Framework
Django REST Frameworkは、Djangoを土台にしたAPI開発向けのツールセットです。認証、権限管理、シリアライザーなど、業務アプリケーションで必要になりやすい機能をまとめて扱えます。管理画面やデータモデルを含む大きめのWebアプリケーションにAPIを追加する場合に適しています。
RESTfulな設計を基本にする
API設計では、リソースを中心にURLを設計し、HTTPメソッドとステータスコードを一貫して使うことが基本です。リソースとは、APIで扱う対象のことです。たとえばユーザー、記事、注文、チケットなどがリソースになります。
設計ルールが揺れると、利用する側の実装が複雑になり、エラー時の調査もしにくくなります。URL、メソッド、ステータスコードの役割をそろえることで、APIの挙動を予測しやすくできます。
エンドポイント設計の基本
- リソースをURLで表す: ユーザー一覧は
/users、特定ユーザーは/users/{id}のように、扱う対象が分かるURLにします。 - HTTPメソッドを使い分ける: 取得は
GET、作成はPOST、全体更新はPUT、部分更新はPATCH、削除はDELETEを使います。 - ステータスコードを適切に返す: 成功時は
200 OKや201 Created、入力不備は400 Bad Request、存在しないリソースは404 Not Foundなど、意味が伝わる応答にします。
FlaskでのRESTful API例
次の例では、ユーザー一覧の取得、特定ユーザーの取得、ユーザー作成を別々のエンドポイントとして定義しています。実際のプロジェクトでは、get_all_usersやcreate_new_userの中にデータベース処理やサービス層の処理を置きます。
from flask import Flask, jsonify, request
app = Flask(__name__)
@app.route('/users', methods=['GET'])
def get_users():
users = get_all_users()
return jsonify(users), 200
@app.route('/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
user = get_user_by_id(user_id)
if user is None:
return jsonify({'error': 'User not found'}), 404
return jsonify(user), 200
@app.route('/users', methods=['POST'])
def create_user():
payload = request.get_json()
user = create_new_user(payload)
return jsonify(user), 201
入力検証とシリアライズを明確にする
APIでは、受け取ったデータをそのまま信頼せず、必須項目、型、形式、長さなどを検証してから処理します。入力検証は、APIに入ってくるデータが処理できる形かどうかを確認する作業です。
あわせて、アプリケーション内部のオブジェクトをレスポンス用のJSONに変換するルールも明確にしておきます。この変換をシリアライズと呼びます。検証とシリアライズの責務を整理しておくと、画面ごと、担当者ごとにレスポンスの形が変わる問題を抑えられます。
Marshmallowを使った検証例
from marshmallow import Schema, fields, validate, ValidationError
class UserSchema(Schema):
id = fields.Int(dump_only=True)
name = fields.Str(required=True, validate=validate.Length(min=1))
email = fields.Email(required=True)
@app.route('/users', methods=['POST'])
def create_user():
schema = UserSchema()
try:
user_data = schema.load(request.get_json())
except ValidationError as err:
return jsonify({'errors': err.messages}), 400
new_user = create_new_user(user_data)
return jsonify(schema.dump(new_user)), 201
エラー時は単に失敗を返すだけでなく、どの項目がなぜ不正なのかを分かる形にすると、API利用者が修正しやすくなります。たとえば、メールアドレスの形式が不正なのか、必須項目が足りないのかを区別して返すと、利用側の実装も安定します。
認証と認可を分けて設計する
セキュリティ面では、誰がアクセスしているかを確認する認証と、そのユーザーが何を実行できるかを制御する認可を分けて考える必要があります。ログインできることと、すべての操作が許可されることは同じではありません。
| 観点 | 意味 | APIでの例 |
|---|---|---|
| 認証 | アクセスしている利用者が誰かを確認する | ログイン、トークン発行、保護されたエンドポイントへのアクセス確認 |
| 認可 | その利用者が対象データや操作にアクセスできるかを判断する | 管理者だけ削除できる、自分のデータだけ閲覧できる、権限ごとに操作を分ける |
JWTを使う場合も、ログイン、トークン発行、保護されたエンドポイント、権限チェックの責務を整理しておきます。FastAPIでのより具体的な考え方は、FastAPIの認証・認可ガイドも参考になります。
FlaskでのJWT認証例
from flask_jwt_extended import JWTManager, create_access_token, jwt_required
jwt = JWTManager(app)
@app.route('/login', methods=['POST'])
def login():
data = request.get_json()
if validate_user(data['username'], data['password']):
access_token = create_access_token(identity=data['username'])
return jsonify(access_token=access_token), 200
return jsonify({'message': 'Bad credentials'}), 401
@app.route('/protected', methods=['GET'])
@jwt_required()
def protected():
return jsonify({'message': 'This is a protected route'}), 200
認証の実装では、秘密鍵やトークンの有効期限、エラー応答、権限チェックの場所をプロジェクト内で統一しておくことが大切です。認証処理が複数の場所に散らばると、あとから権限ルールを変更するときに見落としが起きやすくなります。
非同期処理を活用する場面を見極める
データベースや外部APIへのアクセスなど、待ち時間が発生しやすい処理では、非同期処理が有効な場合があります。特に多くのリクエストを処理するAPIでは、待機時間をどう扱うかがパフォーマンスに影響します。
ただし、すべてを非同期にすればよいわけではありません。非同期処理に対応していないライブラリを無理に組み合わせると、かえって実装が複雑になることがあります。同期処理と非同期処理の境界を整理し、利用するライブラリやデータアクセス方法と合わせて設計します。
FastAPIでの非同期処理例
from fastapi import FastAPI
import asyncio
app = FastAPI()
@app.get('/async-data')
async def get_async_data():
await asyncio.sleep(2)
return {'message': 'This data was fetched asynchronously'}
非同期処理を導入する場合は、どの処理を待たせたくないのかを明確にします。外部API呼び出し、通知処理、時間のかかる集計処理など、待ち時間が発生しやすい部分を見極めると、設計判断がしやすくなります。
APIドキュメントを整備する
APIは、利用する開発者が仕様を理解できてはじめて使いやすくなります。エンドポイント、リクエスト形式、レスポンス例、エラー形式、認証方法を確認できる状態にしておくと、フロントエンドや外部連携の開発が進めやすくなります。
ドキュメントでは、成功時のレスポンスだけでなく、入力不備、認証失敗、権限不足、存在しないデータに対するエラー例も示しておくと実装者に親切です。仕様書と実装が離れないように、APIの変更時にはドキュメントも一緒に更新する運用を決めておきます。
FastAPIでは、エンドポイント定義をもとにSwagger UI形式でAPI仕様を確認できます。たとえば/docsにアクセスして、定義済みのAPIを画面上で確認する構成がよく使われます。
バージョニングで変更に備える
APIは公開後に機能追加や仕様変更が発生します。既存のクライアントに影響を与えないために、バージョニングの方針を早い段階で決めておきます。
- URLパスで管理する:
/v1/usersや/v2/usersのように、URLにバージョンを含めます。 - リクエストヘッダーで管理する: ヘッダーで利用するAPIバージョンを指定し、クライアントごとに切り替えられるようにします。
どちらの方式でも、変更内容、移行期間、古いバージョンの扱いを明確にしておくことが重要です。レスポンス項目の追加、項目名の変更、認証方式の変更などは利用側への影響が大きくなりやすいため、事前に方針を決めておくと安全です。
本番運用前に確認したいポイント
業務APIとして育てていく場合は、設計段階でAPI契約、型定義、認証、テスト、運用監視まで見通しておくと安心です。FastAPIを使う場合の実務的な確認項目は、FastAPIプロトタイプを本番運用へ進める実務チェックリストでも整理しています。
- テスト: 正常系だけでなく、入力不備、認証失敗、権限不足、存在しないデータのケースを確認します。
- エラー形式: 利用者が原因を特定できるように、エラーメッセージとステータスコードの方針をそろえます。
- 変更管理: 既存クライアントに影響する変更は、バージョンや移行期間と合わせて扱います。
- 運用確認: 障害時にどこを見れば原因を追えるのか、ログや監視の方針を決めておきます。
まとめ
PythonでAPIを開発する際は、フレームワークの選定、RESTfulな設計、入力検証、認証・認可、非同期処理、ドキュメント整備、バージョニングを一体で考えることが大切です。これらを最初から意識しておくことで、利用しやすく、保守しやすいAPIに近づけられます。
特に重要なのは、APIを単なる実装ではなく、利用側との契約として扱うことです。URL、メソッド、レスポンス、エラー、認証、変更方針がそろっていれば、開発中も運用後も判断しやすくなります。
実務での検討項目は、PythonとFastAPIで業務APIを作る前に決めることでも詳しく整理しています。
greedenでは、システム開発やソフトウェア設計に関する相談を受け付けています。API設計、既存システムとの連携、事業に合わせた開発方針でお悩みの場合は、greedenのお問い合わせフォームからご相談ください。