設計

外部設計 PART4 APIインターフェース仕様設計書

  1. HOME >
  2. 開発・基盤 >
  3. 設計 >

外部設計 PART4 APIインターフェース仕様設計書

概要

PART3の続きになります。外部設計の中でデータベース設計・テーブル定義書について説明しました。

今回はAPIインターフェース仕様についてになります。最近のシステムはほとんどAPIを作成しているので、必須の知識です。

API設計について思うこと

A君
APIって必要ですか

APIの設計はどうするの?
Aさん

これらの疑問にに解決していきます。

APIの必要性

最近のシステムのほとんどはAPIを作成しています。APIに対してフロント側でリクエストを送って返却してきた値を取得し、連携しています。

今までAPIを使わずにWebシステムを作ってきたのですが、最近の開発はAPIを中心としたものがメインになっています。理由はWebだけでなくiPhoneやAndroidの開発をするときにAPIが必要になるからです。

スマートフォンアプリから直接データベースに参照したり更新をかけることができないため、APIが必要になります。VueやReactといったJavascriptがAPIを取得できるのでWebもAPIとの相性がよく使われています。

そのため、APIが必要になってきたのです。

APIインターフェース仕様設計書

APIインターフェース仕様書はAPIのリクエストをするために何が必要か、レスポンスは何が返却されるのかをわかりやすく解説した仕様書のことです。

まずは具体例からご覧ください。

APIインターフェース仕様の具体例

概要

自宅の温度と湿度のデータをデータベースから抽出します。

共通仕様

プロトコルHTTPS
文字コードUTF-8
content-typeapplication/json

リクエスト

メソッドGET
エンドポイント URLhttps://www.seldnext.com/api/v1/temperatures

ヘッダーパラメータ

順番項目名キー必須説明備考
1認証キーauthorize_keystringログインしている状態か判断するキーを送受信する。

ボディパラメータ

順番項目名キー必須説明備考
パラメータなし

レスポンスパラメータ

順番項目名キー説明備考
1温度tempfloat温度
2湿度Humifloat湿度
3取得日時Created_atdatetime取得したときの時間

APIインターフェース仕様設計書 項目説明

エンドポイント

エンドポイントとはAPIにアクセスするためのURIです。エンドポイントにアクセスすると情報が取得や更新できるのか変わってきます。

例えば/temperaturesのように、温度のデータを取得するために、このようなURIを作成します。

URIを作成する時に命名ルールをわかりやすくしないと解読困難なシステムになりますので注意が必要です。

温度湿度取得API

APIのエンドポイント一覧

どのようなAPIがあるのかを紹介します。基本的には以下のように「Get「Post」「Put」「Delete」の4つのトランザクションを使用します。

Get 温度取得 /temperatures
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仕様書を作っているんですが作成しているという気になっておらず、勝手に作成しているような感じがしています。

私が作成したSwagger

APIインターフェースの作成おすすめの本

ディープラーニング用のAPI作成やグラフQLといった新しい技術も出てきてます。新しい技術が出てくるので参考までにご覧ください。

前回までの外部設計


システム設計
システム開発における外部設計 PART3 テーブル定義

システム開発における外部設計 PART3です。データベース設計についての説明をしています。基礎についての記載になるのでわかりやすく説明していると思います。

続きを見る


システム設計
外部設計 PART2 画面設計と遷移図 ビジネスロジック

外部設計について今回の第2部は画面遷移図、画面設計書、ビジネスロジックについて説明していきます。画像を取り入れながらどのように作成していけば効率的なのかを解説していきます。

続きを見る


システム設計
外部設計 PART1 方針設計書

システム開発における外部設計とは何か。どのような成果物があるのかを説明していく予定です。第1部は外部設計とは何かと方針設計についての説明をしています。

続きを見る

-設計

© 2020 スリーネクスト