REST API サーバーが返すエラーコード（HTTP レスポンスコード）
まずは、最低限、下記の 3 種類のステータスコードを返すように対応するとよいです。
- 200 … OK
- 400 … Bad Request（クライアント側の不正）
- 500 … Internal Server Error（サーバ側の不正）
その後、徐々に以下のように対応していきます。
- 200 … OK
- 304 … Not Modified（クライアントキャッシュへの対応〈弱いキャッシュ〉。
If-Modified-Since/If-Matchヘッダへの対応） - 401 … Unauthorized（アクセスに認証が必要だが、まだ認証してアクセス権限を取得できていない）
- 403 … Forbidden（そのリソースへのアクセス権限がない〈認可されていない〉）
- 404 … Not Found（そのリソースは存在しない）
- 500 … Internal Server Error
URL にはバージョンを含める
Web API の互換性がなくなることを見越して、URL のパス部分にはバージョン情報を含めておくとよいです（v2 以降で付けるという手もあり）。 次のようにパスのルート直下にバージョン情報を含めることで、シンプルな構成になります。
http://api.example.com/v1/users/
バージョン情報がインクリメントされるということは、その API がやりとりするデータに互換性がなくなることを意味します。 バージョン情報はあくまでインタフェースのバージョンを表しています。 API サーバー側の実装が少し変わったからといって、その都度バージョン情報を更新する必要はありません。