P253 9.1.6 見えないインターフェイスコントラクトに注意する

当頁は、APIドキュメントからは読み解けない仕様のことを説明してくれている。
例えば、ユーザーIDを連動させて、その内部仕様で住所を引っ張って来るような実装があったとする。
それが、自宅か勤務先かなどの区分を引き渡して、それを用いて実装されていたら問題無い。
しかし、これがインデックスの先頭とかを参照するとかであれば把握しきれない。
(ただ、これは見えない仕様というより実装がアンポンタンなだけな例ではあるが…)

とはいえ、知らぬ間にユーザーインタフェースだけでは分からない仕様は作りこんでしまう。
API設計者はその様にならない様に設計、ドキュメントで説明などしなければならない。
また、仕様追加などを行う際に、その様な部分にも影響を与えないかの配慮をしなければならない。

P253 9.1.6 見えないインターフェイスコントラクトに注意する

当頁は、APIドキュメントからは読み解けない仕様のことを説明してくれている。
例えば、ユーザーIDを連動させて、その内部仕様で住所を引っ張って来るような実装があったとする。
それが、自宅か勤務先かなどの区分を引き渡して、それを用いて実装されていたら問題無い。
しかし、これがインデックスの先頭とかを参照するとかであれば把握しきれない。
(ただ、これは見えない仕様というより実装がアンポンタンなだけな例ではあるが…)

とはいえ、知らぬ間にユーザーインタフェースだけでは分からない仕様は作りこんでしまう。
API設計者はその様にならない様に設計、ドキュメントで説明などしなければならない。
また、仕様追加などを行う際に、その様な部分にも影響を与えないかの配慮をしなければならない。

P245 サイレントチェンジ

当ページの解説としては、プロパティの意味を変えてしまうことを指す。
入力であろうが、出力であろうが、それは破壊的変更である。
入力における安全な対応方法は、任意項目としてプロパティを追加する方法のみである。(※1)
(入力データを改変した場合とその作用に関する一覧表はP246に記載有)
※1 必須項目を追加することは破壊的変更にはならないが、既存API実行箇所がエラーになる。

コード値やAPI設計などで知っておいた方が良さげなISO規格

ISO 4217

ISO 4217 - Wikipedia

  • 各種の通貨を表すコードについて規定
  • 3文字の文字コード(JPY, USD, etc...)、3桁の数字(392, 840, etc...)、通貨名称、補助通貨等が定義
  • wikipediaに関連リンク含め綺麗に整備してくれている。
  • 3桁はまずいんではと思ったら、そんな議論がやっぱりされていた(※1)

  日本銀行:ISO 4217- 通貨コードに関する国際規格 - 2015年6月30日

※1 とはいえ、昔は1ビット違うだけで影響大きいので致し方無し。
  また、代替案がそうなるわなと思う内容だったので、ある意味参考になる。

ISO 8601

ISO 8601 - Wikipedia

  • 日付と時刻の表記に関して規定
  • 日本では上記に準拠したJIS X0301 情報交換のためのデータ要素及び交換形式ー日付及び時刻の表記が定義
  • こちらもwikipediaに関連リンクも含めきちんと整備してくれている。

ISO 3166

ISO 3166 - Wikipedia

  • 国名や都道府県や州などの地域などを表すコードについて規定
  • 3部構成
  • これもwikipedia~(以下略)

ISO 5218

ISO 5218 - Wikipedia

  • 生物学的性別を表記するためのコードについて規定
  • JIS X0303で定義されていたが、現在は廃止されている
  • 社会的・心理的性別に関するコード値については当方の調査レベルでは発見できず(※2)

※2 Facebookは批判は覚悟の上、この問題を前進させようとした事はもっと評価されるべきかと
www.cnn.co.jp

ISO 639

ISO 639 - Wikipedia

  • 言語の名称および略号を規定
  • 日本ではJIS X 0412が相当(準拠しているかは調べてない)
  • ISO 639-1, 639-2・・・と複数に分かれている模様

雑記

ISOではないけど

多分こちらを都度確認する事の方が重要かもしれない
コード一覧 | 政府CIOポータル

何故纏めようと思ったか

Web APIの設計(翔泳社) 6.1.4 他の人々にならう で、記載されている内容を元にまとめておこうと思ったため。
なお、当本には以下の様な記載が行われていた。

API設計者に必要なのは、一般的に利用されている規格やプラクティスに従い、さらに(堂々と、あるいはこっそりと)他の設計をコピーすることである。
また、規格を採用する場合は特にそうだが、APIが相互運用可能になる。
おまけに、API設計者としての作業が楽になるため、「車輪の再発明」で時間を無駄にすることもない。
一貫性によって何もかも単純になるように思えるが、残念ながら、常にそうであるとは限らない。

最後の文の通り、必ずしも規定が正とは限らない場面は多々ある。
 ex.) 企業、団体の独自コード体系、ここで変えると色々影響が出るコード体系(泣)
そのため、その部分の折り合いを考えながらコード値設計もしくは吸収方法の検討を行わなければならない。

参考リンク

コード(分類体系)導入実践ガイドブック、API導入実践ガイドブック、APIテクニカルガイドブック
(今は政府CIOポータルに掲載されているが、その内デジタル庁に移管されるか廃棄される想定)
cio.go.jp
forza.cocolog-nifty.com

octokitとGitHubスクリプト

octokitoとは

調べてもいい解説が引っ掛からなかったが、Microsoft Learnに綺麗な解説があった。
docs.microsoft.com

octokit は GitHub API 用クライアントの公式コレクションです。
それらのクライアントの 1 つである rest.js によって、GitHub の REST インターフェイスJavaScript でアクセスできるようになります。

GitHubAPI操作するためのクライアントが何種類かあり(node.js用, ruby用, etc..)、それの総称がoctokitという感じでしょうか。
(書いておきながら自信がいまいち無いけど…)

GitHubスクリプトとは

同じくMicrosoft Learnに解説があった。

GitHub スクリプトは、認証された octokit クライアントを提供するアクションです。

octokitをラップして作成したGitHub Actions用のスクリプトをその様に命名しているという理解で良いのでしょうか。

各クラウド基盤のBIツール

技術評論社 図解即戦力 IT・開発シリーズ

昔大学でナツメ社の図解雑学シリーズが分かりやすくて色々借りていたが、
技術評論社の図解即戦力 IT・開発シリーズがまさにそのIT関連のとこ埋める様な良い分かりやすさだった。
新人とかに簡単なところ詰まってる際に紹介するのに適していそう。
やはりネットで調べると断片的に覚えてしまうので、こういった体系立てた本は必要かと思った。

これを楽勝っすねと読み進めれる様になったら、こっちを勧めてあげる感じか。ただ読め読めと勧めるとプレシャーになるとの事なので、あくまでも聞かれたらに留めないといけない。
toyokeizai.net
なお、図解即戦力シリーズはITだけでなく、業務知識本もラインナップされている。
gihyo.jp