当頁は、APIドキュメントからは読み解けない仕様のことを説明してくれている。
例えば、ユーザーIDを連動させて、その内部仕様で住所を引っ張って来るような実装があったとする。
それが、自宅か勤務先かなどの区分を引き渡して、それを用いて実装されていたら問題無い。
しかし、これがインデックスの先頭とかを参照するとかであれば把握しきれない。
(ただ、これは見えない仕様というより実装がアンポンタンなだけな例ではあるが…)
とはいえ、知らぬ間にユーザーインタフェースだけでは分からない仕様は作りこんでしまう。
API設計者はその様にならない様に設計、ドキュメントで説明などしなければならない。
また、仕様追加などを行う際に、その様な部分にも影響を与えないかの配慮をしなければならない。
当頁は、APIドキュメントからは読み解けない仕様のことを説明してくれている。
例えば、ユーザーIDを連動させて、その内部仕様で住所を引っ張って来るような実装があったとする。
それが、自宅か勤務先かなどの区分を引き渡して、それを用いて実装されていたら問題無い。
しかし、これがインデックスの先頭とかを参照するとかであれば把握しきれない。
(ただ、これは見えない仕様というより実装がアンポンタンなだけな例ではあるが…)
とはいえ、知らぬ間にユーザーインタフェースだけでは分からない仕様は作りこんでしまう。
API設計者はその様にならない様に設計、ドキュメントで説明などしなければならない。
また、仕様追加などを行う際に、その様な部分にも影響を与えないかの配慮をしなければならない。
当ページの解説としては、プロパティの意味を変えてしまうことを指す。
入力であろうが、出力であろうが、それは破壊的変更である。
入力における安全な対応方法は、任意項目としてプロパティを追加する方法のみである。(※1)
(入力データを改変した場合とその作用に関する一覧表はP246に記載有)
※1 必須項目を追加することは破壊的変更にはならないが、既存API実行箇所がエラーになる。
日本銀行：ISO 4217- 通貨コードに関する国際規格 - 2015年6月30日
※1 とはいえ、昔は1ビット違うだけで影響大きいので致し方無し。
また、代替案がそうなるわなと思う内容だったので、ある意味参考になる。
※2 Facebookは批判は覚悟の上、この問題を前進させようとした事はもっと評価されるべきかと
www.cnn.co.jp
多分こちらを都度確認する事の方が重要かもしれない
コード一覧 | 政府CIOポータル
Web APIの設計(翔泳社) 6.1.4 他の人々にならう で、記載されている内容を元にまとめておこうと思ったため。
なお、当本には以下の様な記載が行われていた。
API設計者に必要なのは、一般的に利用されている規格やプラクティスに従い、さらに(堂々と、あるいはこっそりと)他の設計をコピーすることである。
また、規格を採用する場合は特にそうだが、APIが相互運用可能になる。
おまけに、API設計者としての作業が楽になるため、「車輪の再発明」で時間を無駄にすることもない。
一貫性によって何もかも単純になるように思えるが、残念ながら、常にそうであるとは限らない。
最後の文の通り、必ずしも規定が正とは限らない場面は多々ある。
ex.) 企業、団体の独自コード体系、ここで変えると色々影響が出るコード体系(泣)
そのため、その部分の折り合いを考えながらコード値設計もしくは吸収方法の検討を行わなければならない。
コード（分類体系）導入実践ガイドブック、API導入実践ガイドブック、APIテクニカルガイドブック
(今は政府CIOポータルに掲載されているが、その内デジタル庁に移管されるか廃棄される想定)
cio.go.jp
forza.cocolog-nifty.com
調べてもいい解説が引っ掛からなかったが、Microsoft Learnに綺麗な解説があった。
docs.microsoft.com
octokit は GitHub API 用クライアントの公式コレクションです。
それらのクライアントの 1 つである rest.js によって、GitHub の REST インターフェイスに JavaScript でアクセスできるようになります。
GitHubをAPI操作するためのクライアントが何種類かあり(node.js用, ruby用, etc..)、それの総称がoctokitという感じでしょうか。
(書いておきながら自信がいまいち無いけど…)
昔大学でナツメ社の図解雑学シリーズが分かりやすくて色々借りていたが、
技術評論社の図解即戦力 IT・開発シリーズがまさにそのIT関連のとこ埋める様な良い分かりやすさだった。
新人とかに簡単なところ詰まってる際に紹介するのに適していそう。
やはりネットで調べると断片的に覚えてしまうので、こういった体系立てた本は必要かと思った。
![Practical Developers ――機械学習時代のソフトウェア開発[ゲームアプリ/インフラ/エッジ編] (WEB+DB PRESSプラスシリーズ)](https://m.media-amazon.com/images/I/517cfsnY5VL._SL500_.jpg "Practical Developers ――機械学習時代のソフトウェア開発[ゲームアプリ/インフラ/エッジ編] (WEB+DB PRESSプラスシリーズ)")
