OpenAPIで書けてもRESTとは限らない、図面と設計思想の正しい関係

OpenAPIで書かれた立派な仕様書を見せられ、うちはRESTで設計しています、と説明されることがあります。けれども、図面がきれいに描けていることは、その建物が耐震設計であることの証明にはなりません。OpenAPIは、RESTでないHTTPのAPIも同じ書式で描けるからです。この記事では、REST APIとOpenAPIの関係を、設計思想と図面というよく知られたたとえで整理したうえで、たとえが言い落としている点と、GPTsのアクションで実際に効くのはどちらなのかを考えます。

RESTは設計の考え方、OpenAPIはそれを書き表す書式です

REST APIは、扱う対象をリソースという単位でとらえ、URIで住所を決め、GET、POST、PUT、DELETEといったHTTPメソッドで操作を表す、Webサービスの設計の考え方です。考え方だけでは相手に伝わらないので、どの住所で、どんな操作を受け付け、何を返すのかを、決まった書き方で書く必要があります。

OpenAPIは、その書き方の規格です。JSONまたはYAMLで、エンドポイント、パラメータ、レスポンスなど、APIの窓口の形を記述します。ユーザー情報を取得するAPIなら、OpenAPI 3.0.0の形式で次のように書けます。

openapi: 3.0.0
info:
  title: ユーザー情報取得API
  version: '1.0'
paths:
  /users:
    get:
      responses:
        '200':
          description: ユーザー情報
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: {type: integer}
                  name: {type: string}

ここから、エンドポイントが /users、メソッドがGET、パラメータはなし、成功すると200のコードとJSONのユーザー情報が返る、と読み取れます。図面があれば、作る人、使う人、確かめる人が同じものを見て話せ、Swagger EditorやPostmanのようなツールでドキュメントの生成、テスト、クライアント用のライブラリの生成もできます。

この図面は、RESTでない建物も描けます

REST APIが設計思想で、OpenAPIが図面。このたとえは正しいのですが、一つ言い落としています。OpenAPIで描けるのはRESTの建物だけではありません。どの操作もPOSTで一つの住所に送り、本文の中で処理の名前を指定する、手続きを呼ぶ形のAPIも、OpenAPIで書けます。前のやり取りを覚えている前提で動くAPIも書けます。

OpenAPIが確かめるのは、書式が規格どおりかどうかです。設計がRESTの考え方に沿っているかは確かめません。書式が整った仕様書ほど、中身の設計まで確かめた気になりやすいのは、見た目の整い方と中身の正しさを、人がつい同じものとして扱うからです。仕様書を受け取ったら、リソース単位で住所が切られているか、リクエストがそれだけで完結しているか、と設計のほうを別に問う必要があります。

もっとも、社内の一つのチームだけで使うAPIなら、RESTかどうかの区別はあまり問題になりません。区別が効くのは、外部の相手と、RESTという言葉だけで期待をそろえようとするときです。

GPTsが読むのは、思想ではなく図面です

ChatGPTを自分用にカスタマイズするGPTsには、外部のAPIを呼び出すアクションという機能があります。登録するのは、OpenAPIの形式で書いたスキーマです。GPTはそれを読んで、どのエンドポイントに、どのメソッドで、何を送ればよいかを判断します。

GPTsは、相手のAPIがRESTの考え方に忠実かどうかを気にしません。読むのは図面に書かれた住所と説明だけです。RESTらしさの議論には熱が入るのに、各操作の説明欄は一行で済ませる、という配分は、力の入れどころが逆さまです。GPTが呼ぶ場面を判断する手がかりは、その一行しかないからです。RESTの考え方のうちGPTsで効いてくるのは、ステートレスです。GPTの送るリクエストが毎回それだけで意味が通るなら、会話の流れに関係なく、同じように呼べます。

ただし、説明欄をどう書けばGPTがどう判断するのかは、外からは正確には分かりません。どこまでがRESTかという線にも、広く合意されたものはありません。図面と思想のどちらも、使ってみた結果から推し量るしかない部分が残ります。

あなたが受け取った、あるいは書いたAPIの仕様書で、書式は整っているのに、設計の考え方を誰も確かめていない部分はどこでしょうか。そのAPIをGPTに渡したとき、GPTが頼れる手がかりは、説明欄の何行でしょうか。

この記事の背景にある考え方は、拙著『ChatGPT 誰でも1時間でできる！ はじめてのGPTsのつくり方』の3章3節「GPTsにおける要件定義の意味と必要性」に書きました。GPTsでは使う人と作る人が同じになっても、作る人の頭の中とAIの理解の間には隔たりが残り、要件を曖昧さなく書くことでしか埋まらない、という節で、その隔たりを「それはあなたとAIとのギャップです。」と書きました。画面や機能は2024年時点の記述ですが、この節を読むと、整った仕様書の中で、GPTに届いているのは何行で、届いていないのはどの意図かを点検できるようになります。

出典

• OpenAPI Initiative
• REST API と OpenAPI の概要
• Swagger Editor
• Postman