初心者Web開発者の Web API 製作メモ＆ノウハウ集

wagahaihanekodearu

ここ最近 PHP 使って iOS や Android 向けにちょっとした API 作ることが多いんだけど、どんな風に設計するのがよいのかいっつも迷います(^_^;) メンテし易く効率良いAPI作りたいんで、色々と探ってみるかなぁ～、、、

■．索引

○そもそもWebAPIって？
○WEB APIのURL設計
○レスポンスはXMLか？JSONか？
○API設計に関する10のワーストプラクティス
○APIのセルフテストしよーぜ
○WebAPI 設計メモ
○API仕様サンプル
○読み物リンク集
○参考ドキュメント
○PHP関連まとめ
・PHPの備忘録～意外と簡単Ajax用にAPIを作っちゃお！
・PHPの備忘録～オブジェクト指向のためのクラス定義ノウハウ集
・PHPの備忘録～初心者トラブルやノウハウ集～

■．そもそもWebAPIって？

Web APIとは、ひとことで言えば、インターネット（Web）を経由して、何らかの処理を行うための、手段や決めごと（API）のことです。APIとは、Application Program Interfaceの略で、直訳すると、あるプログラムを、他のアプリケーションから利用するためのインターフェース、という意味になります。
Web APIの基本とAndroidアプリ開発の準備（1/3）：CodeZine

codezine.jp

Web APIを利用したプログラムの実行

■．WEB APIのURL設計

○WEB APIのURL設計のトレンドはこれだ！

有名サービスのAPIのURL設計が一覧でまとめられてます＼(^o^)／

そのURLがAPIであることを表す方法は大きく分けて2種類あります。サブドメインに置き http://api.example.com/ とするか、パスに置き http://example.com/api/ とするか、です。
WEB APIのURL設計のトレンドはこれだ！WEB APIのURL設計まとめ | 三度の飯とエレクトロン

Facebook や Twitter は種類によってサブドメインがわかれているが, ひとつのまとまっている方がよい
Web API 設計のベストプラクティス集 “Web API Design – Crafting Interfaces that Developers Love” – フリーフォームフリークアウト

複数に訳ないと困るような規模の開発はしてないやｗｗ
てかっ、自分が使う側だとしても１つにまとまってた方が嬉しいかな。

■．レスポンスはXMLか？JSONか？

公開されているWeb APIのなかには、XML形式とJSON形式の両方に対応しているものもあれば、どちらか一方だけしか対応していないものもあります。

JavaScriptでのあつかいやすさ、形式のシンプルさでは、JSON形式のほうが優れているため、今後はXML形式よりJSON形式のものが増えそうです。
Web APIの基本とAndroidアプリ開発の準備（2/3）：CodeZine

両方サポート仕様とすると地味に開発コストが、、、
小規模のWebAPIしか作ったことないけど、JSONで十分。
てかJSONが使いやすい（＾ｕ＾）

それに、クライアント側開発者からも、どっちかといえばJSONでお願いされますね。

■．API設計に関する10のワーストプラクティス

【API設計に関する10のワーストプラクティス】
１．貧弱なエラーハンドリング
２．HTTPのルールを無視したREST API
３．裏に潜んだ生のデータモデルの露出
４．セキュリティの複雑さ
５．ドキュメント化されていない予期せぬリリース
６．貧弱なデベロッパエクスペリエンス
７．MVC（Model-View-Controller）フレームワークが良いAPIにしてくれるという思い込み
８．開発すれば使ってもらえるとみなすこと
９．不十分なサポート
１０．貧弱なドキュメント
API設計に関する10のワーストプラクティス：海外テック情報局｜gihyo.jp … 技術評論社

■．APIのセルフテストしよーぜ

「APIを提供するときは、API自身のテストだけではなく、必ずそのAPIを利用するコードのユニットテストも書く」

もし、API を実際に使わなければ、その設計が良いのか悪いのかを判断することは出来ないですし、結果として誰も使わないような API になってしまうかもしれません。
Typetalk のアーキテクチャ – API を中心にすえたサービス設計 | Nulab 日本語ブログ

これはあるかも。

内部ロジックをデバッグ実行してテストするのと、
実際にクライアント作ってテストするのじゃ感じ方が大分違うよ(^_^;)

■．WebAPI 設計メモ

www.slideshare.net

■．API仕様サンプル

○2. API仕様 – ヤマレコ Web API

ヤマレコ Web API Search this site Home API仕様 1. OAuth認証 2. API仕様 3.ヤマメモAPI サンプルコード Android ファイル利用規約・ガイドライン更新履歴 Sitemap API仕様 > 2. API仕様 1. 基本仕様 1.1 リクエストURL http://api.yamareco.com/api/v1/ または http…

独自のWebAPIを公開されているサイトっぽいです。
こういうの作ってみたいですね（＾ｕ＾）

WebApiの仕様公開するときの参考にしたいです。

○9. Web APIによるCADの実行制御 — CIRCUS 4.0 documentation

Navigation index next | previous | CIRCUS 4.0 documentation » CIRCUS CS 管理者ガイド » 9. Web APIによるCADの実行制御 ¶ CADジョブ登録などの一部操作は、ユーザがWebブラウザを介して操作するほかに、CIRCUS CSが公開しているWeb APIを用いて、外部プログラムから実行することも可能です。例えば、…

レスポンスデータ検討時に参考にしたいかも。

■．読み物リンク集

○Kazuho’s Weblog: 拡張可能なWeb APIの設計原則と、バージョン番号を使う理由について

Kazuho’s Weblog Monday, March 10, 2014 拡張可能なWeb APIの設計原則と、バージョン番号を使う理由について APIのバージョニングは限局分岐でやるのが良い – Hidden in Plain Sight にはブコメしたのですが、 Rebuild: 35: You Don’t Need API Version 2 (Kenn Ejima) でも本件に言…

○Web API 設計のベストプラクティス集 “Web API Design – Crafting Interfaces that Developers Love” – フリーフォームフリークアウト

ブログトップ記事一覧ログイン無料ブログ開設フリーフォームフリークアウト 2013-01-21 Web API 設計のベストプラクティス集 “Web API Design – Crafting Interfaces that Developers Love…

○Web API Design – 開発者が愛するインターフェイスを作る

企業および開発者向けAPIプロダクトおよびテクノロジープロバイダのApigeeは、Web API設計に関するフリーの電子書籍「Web API Design: Crafting Interfaces that Developers Love」をリリースした。ここには、Apigee設計ワークショップを経験した世界中のAPI設計チームの協力のもと作られたREST API設計プラクティスがまとめられてい…

○Webを支える技術 ── HTTP，URI，HTML，そしてREST

○APIのバージョニングは限局分岐でやるのが良い – Hidden in Plain Sight

ちょっと前にTwitterでAPIのバージョニングをどうやるかみたいな話をしていたのですが、そのへんもやもやしているので少し整理しておきたいなと。 APIのURLを/api/v1/*とかってやるの、やめたほうがいいとおもうんだけどなぁ。いざv2を作るとなったときに、大量のコピペが発生して後悔するよ、って伝えたい。— K…