Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationEventAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
565
Help us understand the problem. What are the problem?

More than 5 years have passed since last update.

posted at

updated at

api開発に失敗しないための情報収集まとめ

はじめに

iPhoneやandroid、フロントエンドJavascriptとのAjax通信のためにサーバー側でAPI開発をする時、どんな設計にするのが良いか情報収集していたのですが、その結果をまとめておこうと言う事で書きました。各項目ごとに参考資料もあるので、皆さんがAPI設計をする際の参考としてご活用ください。

どんなバージョニング方法があるか

バージョニング方法は以下の4つがあります。それぞれメリット・デメリットがあるので、その中からサービスの特徴に適した方法を選択します。

1. http headerをカスタムしてapi-versionを書き込む

ex) x-api-version: 1

オンライン・オフラインの区別がほとんどないサービスに有効。OAuthベースシステムのサービスとも親和性が高い。api-versionの指定がヘッダーにない場合は最新を使うのが一般的。

使用例

2. http content-typeに含める

ex) application/com.xxxx.v2+json

使用例

3. パラメータ形式

ex) /api/xxxx?api_version=1

4. ルーティングに含める

ex) /api/v1/xxxx, /api/v2/xxxx

(参考資料)
api ux
O'REILLY community
github developer blog

バージョンごとにファイルをつくらない

xx.com/v1/xxxxx.com/v2/xxxがあるときに、v1フォルダとv2フォルダを作らない。
コピペバージョニングを行ってしまうと、v2を作成時にメンテナンス性が下がります。v2を作成しようとした時点で「あ、これはメンテ出来ないや・・・」という事に気がつく。というより、プログラマとして面白くない設計になってしまう。

限定分岐のバージョニングにしましょう。

例えば5個のapiコントローラがあるときに、1個のapiコントローラだけ内容を変更する場合は、例えばそのコントローラ内にバージョン分岐の処理を加えるようにしましょう。

リソースとコントローラは別だという事を意識しましょう。

リソースとコントローラをつなげる役割を担うのはRoutingです。RubyOnRailsだとActiveResourceです。ActiveResourceが何のためにあるのかを忘れないようにしましょう。

(参考資料)
APIのバージョニングは限局分岐でやるのが良い

外部デベロッパー向けAPIと内部デベロッパー向けAPIを別APIにする

(参考資料)
rebuild.fm/35

HATEOAS形式で返す

HATEOASとは?

Hypermedia As The Engine Of Application Stateの略。
RESTfulパターンを拡張したアーキテクチャパターン。

そもそも、Hypermediaって?

クライアントが次にする事をリンクから選べるようにする事。
Hypermedia : Hyper(最高の)+ media(情報提供媒体)

具体的な形式

  • リンクでリソース間のrelationを表す事
  • リンクで次に可能なアクションを表す
xxx:{
  name: yyy,

  link: {
    rel: "self",
    url: "xxx.com/xxx/1"
  }
}

(参考資料)
Hypermedia The Missing Element
Spring article
REST: From GET to HATEOAS
Grails document

Web APIは HTML Webアプリと同じように設計する

Web APIは特別なものではなく、ただ表現フォーマットが違うだけ。同じ扱いにするべきもの。

(参考資料)
webを支える技術(本)

API開発者Tips

  • クライアントが増えるとAPIが増えるという悩みにぶつかる。
  • LSUEという言葉がある。
  • オーケストレーション層をつくるのが流行りだしている。 (参考資料) TNW Blog
  • サーバー側ではなく、クライアント側がAPIを開発するという考えがある。mBaaSのparse.comが似た形を実現。

その他参考資料

最後に

もう少し整理してから投稿したかったのですが、途中で力尽きました(笑)。
今後も少しずつ改訂していって資料をまとめていく予定です。

最後の最後に

APIバージョニングに未だ銀の弾丸はないそうです。ぜひ銀の弾丸が見つかるよう、何か追加情報及び意見等あれば気軽に書き込んでもらいたいです。^^

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
565
Help us understand the problem. What are the problem?