概要
PART３の続きになります。外部設計の中でデータベース設計・テーブル定義書について説明しました。
今回は「APIインターフェース仕様」がテーマになります。最近、大半のシステムはAPIを作成しているので、必須の知識です。
目次
API設計について思うこと
これらの疑問にに解決していきます。
システム開発にAPIが必要な理由
今までAPIを利用せずにWebシステムを作ってきたのですが、最近の開発はAPIを中心としたものがメインになっています。
理由はWebだけでなくiPhoneやAndroidといったスマートフォンやIoTの機器と連携するときにAPIが必要になるからです。スマートフォンアプリから直接データベースに参照したり更新をかけることができないため、APIが必要になります。簡単な図はこちらです。
WebもAPIにする理由はVueやReactといったJavascriptがAPIを取得できるのでWebもAPIとの相性がよく使われています。また、IoTも流行りつつあり、IoTこそAPIを利用して機器の操作をすることが増えてきています。そのため、APIが必要になってきたのです。
APIインターフェース仕様設計について
APIインターフェース仕様書はAPIのリクエストをするために何が必要か、レスポンスは何が返却されるのかをわかりやすく解説した仕様書のことです。
WebAPIの設計方法について書かれた比較的新しい本です。図で書かれていてわかりやすく読み応えがあります。今後のAPI設計の指南書になる本なのでおすすめです。
APIインターフェース仕様の具体例
概要
自宅の温度と湿度を計測するAPIがあり、計測された温度と湿度のデータをフロント側からサーバーサイドにリクエスト送りデータベースから抽出しJSON形式に加工します。そしてフロントエンドに返す処理の設計です。
共通仕様
| プロトコル | HTTPS |
| 文字コード | UTF-8 |
| content-type | application/json |
リクエスト
| メソッド | GET |
| エンドポイント URL | https://www.seldnext.com/api/v1/temperatures |
ヘッダーパラメータ
| 順番 | 項目名 | キー | 型 | 必須 | 説明 | 備考 |
| 1 | 認証キー | authorize_key | string | ○ | ログインしている状態か判断するキーを送受信する。 |
ボディパラメータ
| 順番 | 項目名 | キー | 型 | 必須 | 説明 | 備考 |
| パラメータなし |
レスポンスパラメータ
| 順番 | 項目名 | キー | 型 | 説明 | 備考 |
| 1 | 温度 | temp | float | 温度 | |
| 2 | 湿度 | Humi | float | 湿度 | |
| 3 | 取得日時 | Created_at | datetime | 取得したときの時間 |
APIインターフェース仕様設計書 項目説明
エンドポイント
エンドポイントとはAPIにアクセスするためのURIです。エンドポイントにアクセスすると情報が取得や更新できるのか変わってきます。
例えば/temperaturesのように、温度のデータを取得するために、このようなURIを作成します。
URIを作成する時に命名ルールをわかりやすくしないと解読困難なシステムになりますので注意が必要です。
温度湿度取得APIAPIのエンドポイント一覧
どのようなAPIがあるのかを紹介します。基本的には以下のように「Get「Post」「Put」「Delete」の４つのトランザクションを使用します。
Post 温度登録 /temperatures
Put 温度更新 /temperatures
Delete 温度削除 /temperatures
他にもPatchやOption等のトランザクションもありますがほとんど使わないので割愛します。
API リクエスト
リクエストパラメータは何でレスポンスパラメータは何なのか。成功したのか失敗したのかはHTTPステータスパラメータを返すことができます。
そのことがこと細かく記載してあります。
レスポンス
APIにアクセスして返却されてくるデータ群をレスポンスと言います。
Open API(Swagger)
RestFul APIの世界標準のインターフェース仕様書です。
APIのインターフェース仕様は以下の画像の通りです。
もともとSwaggerとして世に出ていましたが世界標準として利用されていくうちに名前がOpenAPIに変わりました。ただ、Swaggerという名前が浸透していたのでそのままSwaggerという名称を使い続ける人が多いです。私もSwaggerという名称に慣れているので以降Swaggerと呼びます。
SwaggerはYamlファイルかJSONファイルでAPIの仕様を作成していきます。Swaggerを使うと実際にリクエストパラメータを送るとレスポンスデータが返ってくる用に作られているので実際に疎通できるかどうか確認することができ大変便利です。
PHPやGo言語のアノテーションでSwaggerの自動生成することができます。そのアノテーションでSwaggerドキュメントを作成することができます。
サーバーサイドエンジニアとしてやっていて、API仕様書を作っているんですが作成しているという気になっておらず、勝手に作成しているような感じがしています。
APIインターフェースの作成おすすめの本
ディープラーニング用のAPI作成やグラフQLといった新しい技術も出てきてます。新しい技術が出てくるので参考までにご覧ください。
WebAPIの設計方法について書かれた比較的新しい本です。図で書かれていてわかりやすく読み応えがあります。今後のAPI設計の指南書になる本なのでおすすめです。
RESTfulAPIの代表的な本になります。若干古いのですが命名ルールや設計思想については時代と変わらないので指南書として利用されている人も多いです。
API作成に最近では当たり前になってきているgRPCです。新しいことを試す企業は大抵gRPCを使ったAPI開発が進んでいます。
RESTfulAPIではなく最近の新しい流れでGraphQLが流行ってきていますのでこの機会に勉強されてはいかがでしょう。
前回までの外部設計
最近特に注意が必要なセキュリティの設計から運用方針を定める運用設計、それと品質を担保するためのテスト設計の３点について概要を説明してきます。どれも必須観点ばかりですので設計に携わるのであれば読んでおいてください。 続きを見る システム開発における外部設計 PART3です。データベース設計についての説明をしています。基礎についての記載になるのでわかりやすく説明していると思います。 続きを見る 外部設計について今回の第2部は画面遷移図、画面設計書、ビジネスロジックについて説明していきます。画像を取り入れながらどのように作成していけば効率的なのかを解説していきます。 続きを見る システム開発における外部設計とは何か。どのような成果物があるのかを説明していく予定です。第1部は外部設計とは何かと方針設計についての説明をしています。 続きを見る
外部設計 PART5 セキュリティ設計・運用設計・テスト設計
システム開発における外部設計 PART3 テーブル定義
外部設計 PART2 画面設計と遷移図 ビジネスロジック
外部設計 PART1 方針設計書