API/設計

• 5分で絶対に分かるAPI設計の考え方とポイント
• Web API 設計入門

• Technical Note - Web API The Good Parts
• 翻訳: WebAPI 設計のベストプラクティス
• 綺麗なAPIを設計するには気をつけたい5つのポイント
• 使い勝手や拡張性を担保できるAPI設計には、設計時のルール作成が不可欠

• GoogleのWebAPI設計とWebAPI設計のベストプラクティスを比較してみる
• 「WebAPI 設計のベストプラクティス」に対する所感

• WebAPIの設計から実装まで〜設計編〜
• WebAPIの設計から実装まで〜実装編〜

• API 設計: gRPC、OpenAPI、REST の概要と、それらを使用するタイミングを理解する
• Swagger、GraphQL、gRPC+Protocol Buffersの概観

• OpenAPI や Protocol Buffers のおかげで開発がかなり捗っている話
• マイクロサービスにおけるWeb APIスキーマの管理 ─ GraphQL、gRPC、OpenAPIの特徴と使いどころ

• ASP.NET CoreでgRPCサービスを作ってみた
• IoTと業務システムをつなぐgRPC/RESTサービスの開発と運用

リクエスト †

エンドポイント †

• Web API 設計の基本を学ぶ（APIエンドポイント）
• SPA開発におけるWeb API設計入門（エンドポイント編）

URI †

• 動詞ではなく名詞を用い、複数形とする
• スネイクケース推奨
  • 但し、ドメイン名ではスネイクケースが使用できないことに留意
• APIのバージョンをURIに含める
  • バージョン番号は「v」+「整数」（例：v1, v2, ...）
• ベースURIにAPI提供を表す「api」という単語を含める

パラメタ †

• 1つのパラメタに複数の値を指定する際にはカンマ「,」を用いる

ページネーション †

• RESTful API のページネーションで考えるべきこと
• Web Api でずれないページネーションとSQL
• REST APIのデータ制御について(クエリ、ページネーション)

• limit/offset型
  • 取得開始ページ「offset」または「page」と件数「limit」とする

• ページ番号型
  • ページ番号「page」とする

• カーソル型
  • 「cursor」で開始するデータの ID を指定
  • データ量が多い場合に備えて「limit」も指定できるようにする

レスポンス †

• RESTful APIのHTTPステータスコード設計

文字コード †

• UTF8

データ表記 †

日時 †

• ISO 8601 - WIkipedia
• ISO 8601 の時刻表記
• Date and Time API 復習

• ISO8601に準拠
• 日本時間の場合：YYYY-MM-DDTHH:mm:ss+0900

性別 †

• システムで「性別」の情報を扱う前に知っておくべきこと

• ISO5218に準拠
• 男性は 1、女性は 2、それ以外は 9、不明な場合は 0

メタデータ †

• API はメタデータを提供せよ LT#1 JJUG_CCC2018

エラー †

• RESTful APIのエラー設計
• WebAPIでエラーをどう表現すべき？15のサービスを調査してみた

データ項目 †

• status ... HTTPステータスコードをHTTPレスポンスヘッダに格納
• type ... エラーの種別を示すURIを格納
• title ... エラーの名称を表示
• detail ... エラーの説明文を格納

セキュアなエラーフィードバック †

• 403 Forbidden
  • データへのアクセス不許可 → データが存在することを暗に認めていることになる
  • 「404 Not Found」レスポンスに変えることも検討する

• 500 Internal Server Error
  • APIのベースとなっている技術スタックに関する詳細情報が提供されないようにすること
  • APIの内部で実際に稼働しているものの手がかりになるような情報を提供しないように注意する必要がある

HAL (Hyper Application Language) †

• HAL - Hypertext Application Language

• Web APIにはJSONベースのフォーマットを使おう

ファイルアップロード †

• WebAPI でファイルをアップロードする方法アレコレ