先生と生徒の会話形式で理解しよう

生徒

「FlaskでURLに何か情報をつけて、プログラムに渡せますか？」

先生

「はい、URLの末尾にパラメータをつけてFlaskで受け取れます。クエリ文字列とパスパラメータという方法がありますよ。」

生徒

「クエリ文字列？パスパラメータ？それぞれどう違うんですか？」

先生

「わかりやすく説明しますね。両方ともURLを使ってデータを送りますが、使い方が少し違います。」

1. クエリ文字列とは？初心者向け説明

クエリ文字列とは、URLの末尾に「?」と一緒に「キー＝値」を追加して情報を渡す方法です。たとえば「?name=Taro&age=25」のように書きます。

イメージとしては、レストランで追加注文したい時に、伝票にメモで「サラダ2、ジュース1」など書いて店員さんに渡す感じです。

2. パスパラメータとは？直感的なイメージ

パスパラメータは、URLの途中に変数のような値を埋め込んで情報を渡す方法です。例：「/user/123」なら、123というIDを渡しています。

これは、道を歩いていて「123番地の家を訪ねる」とイメージするとわかりやすいですよ。

3. Flaskでクエリ文字列を使う例

以下は、クエリ文字列を使って名前と年齢をFlaskで受け取るサンプルコードです。


from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/query')
def query_params():
    name = request.args.get('name', '名無し')
    age = request.args.get('age', '年齢不明')
    return jsonify({
        'name': name,
        'age': age
    })

if __name__ == '__main__':
    app.run(debug=True)

このコードはURLに「?name=Hanako&age=30」を追加してアクセスすると、それを受け取ってJSONで返します。

4. Flaskでパスパラメータを使う例

次はパスパラメータを使って、URLの中の値を受け取る例です。


from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/user/<username>/<int:age>')
def user_profile(username, age):
    return jsonify({
        'user': username,
        'age': age
    })

if __name__ == '__main__':
    app.run(debug=True)

このコードは「/user/Taro/25」とアクセスすると、Taroと25を受け取ってJSONを返します。

5. クエリ文字列とパスパラメータの違い

クエリ文字列：URLのあとに「?」で追加。オプションの情報に適しています。
パスパラメータ：URLのパス内。必須で、主に識別子（IDなど）を渡すときに使います。

例えば、商品IDやページ番号など、なくては困る情報はパスパラメータ、それ以外の細かいオプション情報はクエリ文字列として使うのが一般的です。

6. 実際のリクエスト例と返り値

クエリ文字列の例：「http://localhost:5000/query?name=Hanako&age=30」


{"name":"Hanako","age":"30"}

パスパラメータの例：「http://localhost:5000/user/Taro/25」


{"user":"Taro","age":25}

7. パラメータがないときの対策

パラメータが指定されなかったとき、デフォルト値やエラーメッセージを用意しておくとユーザーフレンドリーです。


@app.route('/query')
def query_params():
    name = request.args.get('name')
    if not name:
        return jsonify({'error': 'nameパラメータが必要です'}), 400
    age = request.args.get('age', '年齢不明')
    return jsonify({'name': name, 'age': age})

8. パラメータを使ったAPI活用イメージ

パラメータ付きAPIは、検索機能や詳細表示、絞り込みなどに便利です。たとえば、商品一覧からカテゴリやキーワードで絞り込むときにクエリ文字列が使われますし、特定の商品IDを指定して情報を取り出すときはパスパラメータが使われます。

このようにURLパラメータを活用することで、自分で使いやすいAPIを設計できます。

まとめ

FlaskのAPIで扱うクエリ文字列とパスパラメータは、WebアプリケーションやAPI開発の基礎として非常に重要な概念です。今回の記事では、それぞれの特徴や用途の違い、Flaskでの実際の使い方、デフォルト値の設定やエラー処理など、初心者でも理解しやすいように整理しながら学びました。クエリ文字列は「追加注文を書いた伝票」のようなイメージで、必要に応じて柔軟に付け足せるオプション情報を扱う際に便利です。一方でパスパラメータは「住所の番地」のように、欠かせない識別子を明示的に指定するための方法であり、商品IDやユーザーIDなど、アプリの中で重要な値を扱う場合に適しています。実際のFlaskコードでは、request.args.getでクエリ文字列を受け取り、URLの構造に変数を埋め込むことでパスパラメータを扱うことができました。それぞれにメリットがあり、用途によって使い分けることで、より読みやすく、使いやすいAPIを設計できます。特にAPIでは、クエリ文字列で柔軟な検索機能を実現したり、パスパラメータで明確なリソース指定を行ったりする場面が多く、今回の知識はそのまま実務にも応用できます。また、パラメータが渡されなかった場合のエラー処理やデフォルト値の設定は、ユーザーにとってわかりやすいAPI設計に直結するため、丁寧に実装することが大切です。さらに、パラメータを活用したAPIは、商品検索、ユーザープロフィール表示、絞り込み機能、ページネーションなど、多くのWebアプリケーションで必須となる場面があり、Flaskの基本構文を理解しておくことでより豊かな機能を実現できます。記事で紹介した具体例を振り返りながら、自分のアプリケーションでも柔軟に取り入れられるようになると、API全体の設計力も大きく向上します。下記では、今回の学びを整理しながら、実際に使えるサンプルコードをまとめています。

クエリ文字列とパスパラメータのサンプルコード


from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/search')
def search_items():
    keyword = request.args.get('keyword', 'なし')
    category = request.args.get('category', '未指定')
    return jsonify({
        '検索キーワード': keyword,
        'カテゴリ': category
    })

@app.route('/item/<int:item_id>')
def item_detail(item_id):
    return jsonify({
        '商品ID': item_id,
        '詳細': f"{item_id}番の商品情報です"
    })

if __name__ == '__main__':
    app.run(debug=True)

このサンプルでは、クエリ文字列を使った検索APIと、パスパラメータを利用した詳細表示APIの両方を実装しています。検索APIではキーワードやカテゴリが指定されなくても対応できるようにデフォルト値を設定し、詳細APIでは指定された商品IDに応じて異なる内容を返す仕組みを備えています。このように、クエリ文字列とパスパラメータを組み合わせることで、アプリに求められる柔軟性と明確な情報指定の両方を満たすことができます。 URLパラメータを適切に活用すると、使いやすく直感的なAPIを構築でき、フロントエンドや外部サービスとの連携もスムーズになります。特に、検索機能やフィルタリング機能、複数条件での絞り込みなどを実装する際には、クエリ文字列が非常に役立ちます。一方、特定のリソースを取得する際にはパスパラメータを使うことで、ユーザーにも開発者にも理解しやすいURL設計が実現できます。今回の学びを活かし、FlaskでのAPI開発に自信を持って取り組めるようになれば、より高度なアプリケーションづくりへと進む準備が整ったと言えるでしょう。

先生と生徒の振り返り会話

生徒

「クエリ文字列とパスパラメータ、用途によってうまく使い分けるのが大事なんですね！最初は違いがよくわからなかったけれど、コード例を見たら理解できました。」

先生

「その通りです。FlaskのAPIはとても柔軟なので、適切にパラメータを使えば使いやすいAPIになりますよ。特に検索機能ではクエリ文字列がよく使われますね。」

生徒

「パスパラメータはIDみたいに必須の情報を渡す時に使うんですよね。URLの中に値が埋まっているのが、実は読みやすいんだなと思いました！」

先生

「理解が深まってきていますね。今回の内容を押さえておけば、APIの設計力がぐんと上がります。今後は複数のパラメータを組み合わせた高度なAPIにも挑戦できますよ。」

生徒

「もっと練習して、自分でAPIを作れるようになりたいです！ありがとうございました！」