APIについてのまとめ(忘備録)

参考文献Web API: The Good Parts

Web API

HTTPプロトコルを利用してネットワーク越しに呼び出すAPI

API

”Application Programming Interface”の略
ソフトウェアコンポーネントの外部のインターフェイス、つまり機能ははわかっているけれどもその中身の実際の動作は詳しくわからない（知らなくて良い）機能のカタマリを、外部から呼び出すための仕様

• HTTPプロトコルを使うため、エンドポイントはURLによって指定される。
• 簡略化「URLにアクセスすることで、サーバー側の情報を書き換えたり、置かれた情報を取得できたりすることが出来るWebシステムで、プログラム側からアクセスしてそのデータを機械的に利用するためのもの」

APIでの利用を前提としたサービス

• IaaS Infrastructure as a Service
• BaaS Backend as a Service
• DaaS Data Storage as a Servie

何をAPIで公開するべきか

そのサービスでできる事全て（コアの価値のある部分全て）をAPI経由で行えるようにする。

APIを公開するリスク

情報・利益が盗まれれる可能性について
→ユーザーが少ない場合・・・不利益はほぼない。情報を有効活用してくれる・付加価値をつけてくる
→ユーザーが多い場合・・・可能性はある。注目を集める。自分のサービスを公式でコントロールできるようにしておかないと逆に危険

API公開で得られる物

サービスの核と離れた、自分で開発する優先度が低いものを他の誰かが開発して、サービスの付加価値を上げてくれる。
評判を下げるAPI利用を取り締まれる。（利用規約を設ける。）

Web APIを美しく設計する必要性

設計の美しいWeb APIは使いやすい
    →使うユーザーは他人かつ複数である。
設計の美しいWeb APIは変更しやすい
    →使うユーザーは変化に敏感とは限らない。
設計の美しいWeb APIは頑強である
    →Webと同じ以上にセキュリティが必要である。
設計の美しいWeb APIは恥ずかしくない
    →APIは開発者に判断される。

Web APIを美しくするには

1. 何をAPIで公開するかを決める
2. アクセス先のエンドポイントを決める
3. やりとりする方法や適切なレスポンスデータの形式を決める。
4. セキュリティやアクセス制限を決める。

原則

• 仕様が決まっているものに関しては仕様に従う。
• 仕様が存在していないものに関してはデファクトスタンダード（de facto standard 事実上の業界標準となった規格）に従う。

対象となる開発者の数とAPIの設計思想

LSUDs・・・large set of unknown developers（未知の多数の開発者）
    →パブリックなAPI（Facebook,twitter）
SSKDs・・・small set know developers（既知の少数の開発者）
    →プライベートなAPI（自社内）

APIとして公開する機能を設計する

公開したAPIがどのように使われるのか、そのユースケースをきちんと考える。

モバイルアプリケーション向けのAPIに必要な機能

1. クライアントアプリケーションの画面とその遷移を考える
2. どんな機能をAPIで提供しなければいけないかを考える。

APIエンドポイントの考え方

エンドポイント・・・APIにアクセスするためのURI
       →APIは多数の機能をもつため複数のエンドポイントがある。

URL ≠ URI

URIの方が広い概念で、URLはURIの 一部分
URL・・・場所を示す書き方のルール
→ページや画像などを取得したりするための場所、アクセス方法の指定

URI・・・名前または場所を識別書き方のルールの 「総称」(ボス)
→URLはURIで定められたルールに従って書かれたり使われたりする

例
寿司(URI)
--握り寿司(URL)
webページのアドレスはURLと呼んでもURIと呼んでもどっちでもよい。

エンドポイントの基本的な設計

原則：覚えやすく、どんな機能を持つURIなのかがひと目でわかる

• 短く入力しやすいURI
• 人間が読んで理解できるURI
  →単語を省略しない（一般的な省略は良しex.jp）・英語・APIでよく使われているもの・スペルミスを確認する。
• 大文字小文字が混在していないURI
• 改造しやすいURI
• サーバー側のアーキテクチャが反映されていないURI
  ルールが統一されていないURI