API を生やすってなに？〜REST 編〜

APIを生やす。 → シンプルに API を作成することです。

動作的には追加する行為ですが、なぜか草木のように生やすというのは業界の謎です。

ソフトウェア業界は変に捻った表現が好きな人が多いですね。

そもそも API ってなに？

API（Application Programming Interface）は、ソフトウェアやサービスが他のソフトウェアやサービスと通信するための仕組みで、データをやり取りしたり、機能を共有したりすることができます。

API にはREST、GraphQL、OPEN等の種類があり、記述方法やバックエンドの実装が異なりますが、基本的な用途は同一で、システムに「API エンドポイント」を用意し、他システムはそこに対して欲しいリクエストを送信する形式になります。

API エンドポイントってなに？

平たく言うとリクエストの投げ先です。

Flask(python) で REST形式のものを記載するとこんな感じです。

このサーバ(localhost:6000)に対して、curl http://localhost:6000/helloを叩くと"Hello, World!"がリターンされます。

故に今回のケースだと'localhost:6000/hello'が API エンドポイントになります。

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/hello', methods=['GET'])
def hello():
    return jsonify({"message": "Hello, World!"})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=6000)

上記の例はシンプルなリクエストになりますが、複数の要素を扱うメモアプリ等だと、エンドポイントにどのようなパラメーターを付与するかも指定してあげます。メモアプリでのサンプルは後述します。

REST API とは？

REST（Representational State Transfer）API は、HTTP プロトコルを使用し、URL と HTTP メソッド（GET、POST、PUT、DELETE など）を組み合わせてリソースを操作する API の設計スタイルです。
REST の原則に従って設計された API は、シンプルで理解しやすく、スケーラビリティに優れているので、WEB 開発において最もポピュラーなものになります。

aws で言うと API Gateway が REST 形式の API エンドポイントをマネージドで提供してくれます。

簡単なハンズオン：REST API の実装と利用

理解促進のために簡単なハンズオンを書いておきます。

メモを作成し、メモリ上に保存する簡単なものです。

環境構築

dockerfile

FROM python:3.12

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "app.py"]

requirements.txt

flask

app.py

from flask import Flask, jsonify, request

app = Flask(__name__)

# メモリ上にメモを保存するための辞書
memos = {}

# メモを作成するエンドポイント
@app.route('/memos', methods=['POST'])
def create_memo():
    data = request.get_json()
    memo_id = len(memos) + 1
    memos[memo_id] = {'id': memo_id, 'title': data['title'], 'content': data['content']}
    return jsonify(memos[memo_id]), 201

# 全てのメモを取得するエンドポイント
@app.route('/memos', methods=['GET'])
def get_memos():
    return jsonify(list(memos.values()))

# 特定のメモを取得するエンドポイント
@app.route('/memos/<int:memo_id>', methods=['GET'])
def get_memo(memo_id):
    if memo_id not in memos:
        return jsonify({'error': 'Memo not found'}), 404
    return jsonify(memos[memo_id])

# 特定のメモを更新するエンドポイント
@app.route('/memos/<int:memo_id>', methods=['PUT'])
def update_memo(memo_id):
    if memo_id not in memos:
        return jsonify({'error': 'Memo not found'}), 404
    data = request.get_json()
    memos[memo_id]['title'] = data['title']
    memos[memo_id]['content'] = data['content']
    return jsonify(memos[memo_id])

# 特定のメモを削除するエンドポイント
@app.route('/memos/<int:memo_id>', methods=['DELETE'])
def delete_memo(memo_id):
    if memo_id not in memos:
        return jsonify({'error': 'Memo not found'}), 404
    del memos[memo_id]
    return '', 204

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=6000)

Docker起動

docker build -t rest-api .
docker run -p 6000:6000 rest-api

利用サンプル

起動した API サーバー(app.py)に対して、curlコマンドを使ってリクエストを送信すると以下のようになります。

リクエストの結果は⇨で示します。

新しいメモの作成

curl -X POST -H "Content-Type: application/json" -d '{"title": "new memo", "content": "new Content!"}' http://localhost:6000/memos

⇨{"content":"new Content!","id":1,"title":"new memo"}

メモ一覧取得

curl http://localhost:6000/memos

⇨[{"content":"new Content!","id":1,"title":"new memo"}]

特定メモを更新（memo_id = 1 の場合）

curl -X PUT -H "Content-Type: application/json" -d '{"title": "update memo", "content": "update Content!"}' http://localhost:6000/memos/1

⇨{"content":"update Content!","id":1,"title":"update memo"}

特定のメモを取得（memo_id = 1 の場合）

curl http://localhost:6000/memos/1

⇨{"content":"update Content!","id":1,"title":"update memo"}

特定のメモを削除（memo_id = 1 の場合）

curl -X DELETE http://localhost:6000/memos/1

ポイント

上記のcurlコマンドを見て分かる通り、↓サーバー側のコードで指定してあげた形式に沿ったリクエストにの対して、処理が実施されます。

@app.route('/memos/<int:memo_id>', methods=['PUT'])

これで、REST API の実装と利用の基本的な流れが体験できたと思います。

最後に

この記事では、「API を生やす」という言葉の意味と API の基礎について解説し、REST API を実際に実装・利用してみました。

次は GrapQL について記事が書けたらなと思っています。

以上、どなたかの参考になれば幸いです。