Web API

Web API とは、Web 上のシステム間インターフェース、つまりデータを受け渡しするための規約のことです。この Web API を実装することで、ブラウザなどから HTTP や HTTPS を通じてデータの受け渡しができるようになります。

Web API はサービス提供側が自由に実装するわけですが、多くのクラウドサービスでは、デザイン思想は REST スタイル、データフォーマットは JSON の Web API が提供されています。

Web API をスキャフォールディング

TreeFrog では、１つテーブルからデータを CRUD する Web API の足場を簡単に作ることができます。
例えば、次のようなテーブルがあったとします。

sqlite> .schema blog
CREATE TABLE blog (id INTEGER PRIMARY KEY AUTOINCREMENT, title VARCHAR(20), body VARCHAR(200), created_at TIMESTAMP, updated_at TIMESTAMP, lock_revision INTEGER);

このテーブルに対して、次のコマンドで Web API の足場を作ります。

$ tspawn api blog
DriverType:   QSQLITE
DatabaseName: db/dbfile
HostName:
Database opened successfully
  created   models/sqlobjects/blogobject.h
  created   models/objects/blog.h
  created   models/objects/blog.cpp
  updated   models/models.pro
  created   models/apiblogservice.h
  created   models/apiblogservice.cpp
  updated   models/models.pro
  created   controllers/apiblogcontroller.h
  created   controllers/apiblogcontroller.cpp
  updated   controllers/controllers.pro

コントローラやサービスクラスなどのソースファイルが生成されました。ここで作られる Web API のデータフォーマットは JSON になります。

Web API のエントリーポイントは次のようにコントローラ apiblogcontroller.h に定義されます。

class T_CONTROLLER_EXPORT ApiBlogController : public ApplicationController {
    Q_OBJECT
public slots:
    void index();                    // 一覧取得
    void get(const QString &id);     // 1件取得
    void create();                   // 新規登録
    void save(const QString &id);    // 保存（更新）
    void remove(const QString &id);  // 1件削除
};

これらのエントリーポイントは次のとおりです。

/apiblog/index
/apiblog/get/(id)
/apiblog/create
/apiblog/save/(id)
/apiblog/remove/(id)

Web API の動作確認

ソースをビルドし、サーバを起動します。

 $ make
 $ treefrog -e dev -d

curl コマンドで Web API の動作確認してみましょう。

$ curl -sS http://localhost:8800/apiblog/index
{"data":[]}

何もデータが登録されていないので、空の JSON データが取得されました。

エントリーポイント追加

デフォルトのエントリーポイントに加え、config/routes.cfg に項目を記述することでエントリーポイントを追加することができます。例えば、次のように記述します。

# Method   Entry-point               Function

get       /api/blog/index           ApiBlog.index
get       /api/blog/get/:param      ApiBlog.get
post      /api/blog/create          ApiBlog.create
post      /api/blog/save/:param     ApiBlog.save
post      /api/blog/remove/:param   ApiBlog.remove

正しく追加されたかをチェックします。

$ treefrog --show-routes
Available routes:
  get     /api/blog/index  ->  apiblogcontroller.index()
  get     /api/blog/get/:param  ->  apiblogcontroller.get(id)
  post    /api/blog/create  ->  apiblogcontroller.create()
  post    /api/blog/save/:param  ->  apiblogcontroller.save(id)
  post    /api/blog/remove/:param  ->  apiblogcontroller.remove(id)

GET や POST の他に PUT や DELETE も追加することができます。詳しくは URL ルーティング のページを参照してください。

curl コマンドで追加したエントリーポイントの動作確認してみましょう。

$ curl -sS http://localhost:8800/api/blog/index    ← 追加したエントリーポイント
{"data":[]}

同じように、空の JSON データを取得することができました。

登録用の Web API

次にデータを 1 件登録してみましょう。curl コマンドで JSON データを POST します。

$ curl -sS -X POST -H "Content-Type: application/json" -d '{"title":"Hello","body":"hello world"}'  http://localhost:8800/api/blog/create

もう一度、一覧を取得してみます。

$ curl -sS http://localhost:8800/api/blog/index
{"data":[{"body":"hello world","createdAt":"2022-05-25T16:39:02.142","id":1,"lockRevision":1,"title":"Hello","updatedAt":"2022-05-25T16:39:02.142"}]}

今後は一覧のデータを正しく取得できました。

ID を指定してデータを取得してみましょう。

$ curl -sS http://localhost:8800/api/blog/get/1
{"data":{"body":"hello world","createdAt":"2022-05-25T16:39:02.142","id":1,"lockRevision":1,"title":"Hello","updatedAt":"2022-05-25T16:39:02.142"}}

正しく取得できました。

返却するプロパティを制限する

スキャフォールディング後のソースでは、DB レコードのカラムの全データが返却されていましたが、返却データ（プロパティ）を制限してみましょう。

サービスクラス apiblogservice.cpp を編集します。

QJsonObject ApiBlogService::index()
{
    auto blogList = Blog::getAll();
    QJsonObject json = { {"data", tfConvertToJsonArray(blogList, {"id", "title", "body"})} };  // ←ここ
    return json;
}

QJsonObject ApiBlogService::get(int id)
{
    auto blog = Blog::get(id);
    QJsonObject json = { {"data", blog.toJsonObject({"id", "title", "body"})} };  // ←ここ
    return json;
}

ビルド後に、curl コマンドで確認してみると、指定したプロパティのみ返却されています。

$ curl -sS http://localhost:8800/api/blog/index
{"data":[{"body":"hello world","id":1,"title":"Hello"}]}

$ curl -sS http://localhost:8800/api/blog/get/1
{"data":{"body":"hello world","id":1,"title":"Hello"}}

まとめ

スキャフォールディングでシンプルな Web API を作成することができました。

実際のケースでは、このスキャフォールディングで作られた実装では不十分でしょう。例えば、2 つ以上のテーブルからデータを取得し、階層化された JSON データを返すことがあります。その場合はサービスクラスなどを適宜修正して、実装してください。