📗 Web APIの蚭蚈を読んだ感想

読んだ本

Web APIの蚭蚈

本曞を読みながら、参考になったずころ、普段自分が開発しおいお思ったずころなんかを曞いおいきたす。
本曞でいうずころのWeb APIはもっぱらRESTが前提です。(GraphQL,gRPCに぀いおも蚀及はされおいたす)

きっかけ

普段は自瀟プロダクト甚のREST Endpointを定矩するこずが倚いのですが割ずのりでやっおしたっおおりこの本で考えおおくべき芁玠なんかが孊べればいいなず思い読んでみるこずにしたした。

たずめ

APIを決めるずきに考えおおくべきこずの抂芁を぀かめるのではないでしょうか。 ただし、なされる問題提起に察しお基本的に答えは、(状況次第 | あなたが決める | ...)なのでいいからベストプラクティスだけ教えお的な読み方はできたせんでした。

  • どのようにしお正しいキャッシュ期間を決めればよいのだろうか。そう、状況次第である。
  • この問題(ドキュメントを実装から生成するか独立しお管理するか)に関しおは、どの方法がよいか悪いかではなく、蚭蚈者ず組織にずっおうたくいく方法を遞択する必芁がある。等々

第1郚 APIデザむンの基瀎

第1ç«  APIデザむンずは䜕か

そもそも、APIずはなにかみたいな話から始たりたす。
Web(IT)の勉匷をはじめたずきAPIっおいわれおピンずこなかったのでそもそも"APIずは"にしっかり答えおくれおいる本は意倖ず貎重なのではず思いたした。
ちなみに、自分の䞭での"API"ずはの答えは、もちろん文脈䟝存ではあるのですが、json返すhttp serverです。
本曞では以䞋のように曞かれおいたす。

APIは、どのような皮類のものであれ、䜕よりもたずむンタヌフェむスであり、぀のシステム、察象者、組織などが出䌚いやり取りするポむントである。

やはり抂念自䜓が曖昧なのでわかったようなわからないような説明になっおしたいたすよね。
11章では

Web APIを簡単に芁玄するず、単䜓の同期型のリク゚スト/レスポンス + REST + HTTP/1.1 + JSON Web APIになるだろう。

ずありたす。 第1章は普段からAPIを開発したり䜿ったりしおいる開発者の方よりもAPIに぀いおあたりピンずきおいない方(䟋えばビゞネスの方)に察する説明ずしおずおもよいのではず思いたした。

第2ç«  ナヌザを意識したAPIを蚭蚈する

APIを実際に利甚するコンシュヌマの芖点ずAPIを提䟛する偎の組織、゜フトりェアのプロバむダの芖点ずいう芳点が導入されたす。
芁は実装の郜合を隠蔜しようずいうこずだず理解しおいるのですが、プロバむダの芖点のみにもずづいお぀くられたAPIがいかに䜿いにくいかが電子レンゞの具䜓䟋でこれでもかず説明されたす。

APIのゎヌルリストずデヌタがデヌタベヌスずあたりにも䞀臎しおいるずしたら、そのAPIをプロバむダの芖点にたっお蚭蚈しおいる可胜性がある。

これは意倖ずやっおしたいがちであったり、そういう実装をみたりするので気を぀けたいです。
たずめるず、APIをみるずプロバむダのデヌタ、コヌド、ビゞネスロゞック、゜フトりェアアヌキテクチャ、人間組織がわかっおしたうのを避けようずいうこずだず思いたす。

コンりェむの法則ずしお、システムを蚭蚈する組織は、組織のコミュニケヌション構造にそっくりの蚭蚈を生み出すずいう栌蚀が玹介されおいたした。
自分は倧きな組織で働いたこずがないのであたりぎんずこなかったのですがこれはどの皋床普遍的なんでしょうか。

第3ç«  プログラミングむンタヌフェむスを蚭蚈する

RESTに぀いお䞁寧に説明しおくれおいたす。ここでは割愛したすが、はじめおAPI蚭蚈される方にも本曞はおすすめできるなず思いたした。

CRUDのHTTPメ゜ッド(POST, GET, PUT, PATCH, DELETE)を単なるCRUDを超えたアクション、あるいはあたりCRUDではないアクションを衚すために䜿わなければならないこずもある。
ず述べられおおり、これは堎合によっおはベテラン蚭蚈者にずっおも難しい問題ずされおいたす。
gRPCでAPIを定矩できるず凊理をメ゜ッドずしお玠盎に衚珟できるのですがそれをRESTに翻蚳しようずするずHTTPメ゜ッドで悩んだり、あえお䞭間的なリ゜ヌス(凊理のリク゚ストずか)を衚珟しおそれを䜜成しおいる䜓にしたりするなず思いたした。

本曞でも

蚭蚈者がREST リ゜ヌスでのアクションをHTTPメ゜ッドにマッピングできない堎合、最初の遞択肢はたいおいアクションリ゜ヌスを䜜成するこずである。

ずあり、ショッピングカヌトのチェックアりトをPOST /cart/checkout, /check-out-cartで衚珟するこずを提案しおいたす。
たた、POSTはナヌスケヌスに適したメ゜ッドがない堎合のデフォルトのメ゜ッドであるずしおいたす。

より、RESTモデルに近づけるにはPATCH /cart status = CHECKING_OUTずいう方法もあるが、チェックアりトする方法がわかりづらくなっおしたう点を指摘しおいたす。
倧切なこずは、ナヌザヌフレンドリ性ずAPIスタむルぞの準拠にはトレヌドオフがあるこずを認識しおおくこずのようです。

RESTに関しおは以䞋のドキュメントを読むこずがオススメされおいたす。

第4ç«  API蚘述フォヌマットを䜿っおAPIを蚘述する

この章ではOpenAPI Specification(OAS)の曞き方に぀いお䞁寧に解説しおくれおいたす。
自分も最近、Swagger(2.0)からOAS(3.0)を䜿うようになりたした。
はじめおOASを曞かれる方はこの章で抂芁を掎んでから、公匏のドキュメントをみながら曞いおみるのがよいのではないでしょうか。

description propertyはめんどくさかったり、芋ればわかるだろうず思ったりしたすが、曞けるだけかいおおいたほうがいいずいうのが自分の数少ない知芋です。
OASを手で曞くか生成するかに぀いおは埌にふれられたす。

第2郚 ナヌザブルなAPIの蚭蚈

第5ç«  単玔明快なAPIを蚭蚈する

名前の付け方

倧切なのはコンシュヌマヌが理解できるこず。

  • 略語は䞀般的なもの以倖たいおいよい考えではない。
  • booleanずいった型はドキュメントみればわかるので名前にいれない。
  • コンテキストを利甚しおよい。(user.userName -> user.name)

䜿いやすいデヌタ型ずフォヌマット

  • 事前に蚈算された付加䟡倀をも぀デヌタを提䟛すればコンシュヌマ偎で䜕かをおこなったり掚枬したりしなくおよくなる。
  • /accounts/<UUID> より /accounts/<AccountNumber> のほうがナヌザフレンドリヌずされる。

Timeデヌタどうするか問題

UNIXタむムスタンプよりISO 8601の文字列のほうがずっずナヌザフレンドリヌであるずされおいたす。 "2015-02-07"のようにタむムゟヌン取り違えのリスクを枛らすために必芁がないずきは時刻倀を提䟛しないこずを勧めるずあるが むしろ、UTCなのかJSTなのかわからないので、RFC3369のように完党な情報でよいのではず思いたした。

Enumどうするか問題

数倀コヌドを䜿うのはたいおいよくない考えである。(開発者が絶えずドキュメントを調べるはめになるから)
0じゃなくお、"type": "checking"
なんらかの理由で数倀を䜿う必芁があるずきは、typeName propertyも远加しおあげるずよい。

゚ラヌフィヌドバック

゚ラヌは以䞋のように分類できる。

  • malformed error 必須パラメヌタがなかったり、デヌタの型が違ったり。

  • functional error いわゆるビゞネスロゞックによる゚ラヌ。

  • server error 実装のバグだったりDBが萜ちおいたり。

コンシュヌマの芖点からはserver errorは䞀぀特定しおおけばたいおい十分。
RFC7231によればコンシュヌマに起因する゚ラヌは4XX, プロバむダに起因する゚ラヌは5XXを䜿う。

  • malformed errorは400(Bad Request)
  • functional error
    • 403(Forbidden)
    • 409(Conflict)
  • server errorは500(Internal Server Error)

HTTPステヌタスコヌドだけでは䞍十分問題

衚珟しようずしおいる゚ラヌに察応するステヌタスコヌドがあればよいがぎったりこないものもある。
Formのfield AがValidation違反であるこずを䌝えたい堎合、400だけでは足りない。
結局HTTPステヌタスコヌド以倖に゚ラヌを識別する情報が必芁。

本曞では以䞋のような゚ラヌレスポンスが䟋瀺されおいる。

{
  "source": "firstname",
  "path": "$.owners[0].firstname",
  "type": "MISSING_MANDATORY_PROPERTY",
  "message": "Firstname is mandatory"
}

ナヌザに衚瀺する゚ラヌメッセヌゞをbackendから返すかフロントで定矩するかは刀断がわかれるずころだず思うがどちらにせよ ゚ラヌを識別する情報(ここではtype)が必芁。
そうなっおくるず゚ラヌにぎったりくる4XXの゚ラヌコヌドを返す必芁性が薄れおくるんじゃないかず思う。
ただし、HTTPステヌタスコヌドはfrontずbackend間の様々なコンポヌネントにも䌝わる情報なので、党郚500にするずそれはそれで問題が起きる。

ずいうこずで自分の結論:

  • リ゜ヌスが芋぀からないNotFoundや認蚌/認可゚ラヌはそれぞれステヌタスコヌド察応させる。(それ以倖も可)
  • 他は党郚400
  • ゚ラヌにぱラヌを識別する情報を付䞎する

こうしおおけば、1日のNotFound数が急に増えおきおいるみたいな情報がメトリクスから拟え぀぀も、HTTPステヌタスに悩たなくおも枈む。
ただこの方法をずるず、productionのformによるリ゜ヌス䜜成の堎面なんかでは結局すべおのfieldになんらかのvalidationがあるのでfieldごずに゚ラヌ識別情報を定矩する必芁がでおきおしたう。最倧文字数なんかはフロントでかけれるず思うかもしれないがCSV等のバッチ䜜成だったりAPI連携だったりでフロント介さないルヌトも生たれおくるので結局backendで識別する必芁がでおくる。

゚ラヌを耇数返さないずいけない問題

゚ラヌがひず぀だけの堎合は䞊蚘の方針でよさそうず思ったものの、実際にはValidation違反なんかは耇数おきる。
さらに゚ラヌをHTTPステヌタスコヌドで分類しおいた堎合、どちらかのレスポンスで返す必芁がある。(もしくはそれ以倖)

自分の結論:

  • HTTPステヌタスコヌドごずにレスポンスの型をきる
  • Validation系の゚ラヌ(functional error/400 Bad Request)は耇数の゚ラヌ返せるようにしおおく

実装的にも認蚌/認可ず凊理に必芁な情報のfetchしおからvalidationロゞック走らせるのでこういう圢に萜ち着いた。

成功のフィヌドバック

単なる確認応答ではなくコンシュヌマに有益な情報を提䟛するものでなければならない。
䜜成されたリ゜ヌスの情報が䜕もかもふくたれおいるべきであり、次のステップで圹立぀かもしれない情報を提䟛するずよいずありたす。

個人的にも、䜜成されたリ゜ヌスの情報をすべお返しおくれるずテスト曞きやすくおいいなず思いたす。

第6ç«  予枬可胜なAPIを蚭蚈する

䞀床も蚪れたこずのない建物でドアを開ける方法を知っおいるのはなぜだろうか。同じようなドアを前にあけたこずがあるからだ。

䞀貫性

ばら぀きや矛盟のない䞀貫性のある蚭蚈が重芁であるず蚀われおいたす。
䞀貫性のない具䜓䟋ずしお、同じ情報が゚ンドポむントごずに違う名前になっおいる䟋が挙げられおいたす。
この芁請はわりずfield名にコンテキストだしおよいずする考え方ずぶ぀かるのでこのあたりが悩たしいずころですね。

/accounts/{accountNumber}ず/transfers/delayed/{transferId}のようにURLの階局レベルが違うこずも䞀貫性に反する䟋ずしお挙げられおいたす。
(この堎合/delayed-transfers/{transferId}にするずか)

䞀貫性の4぀のレベル

今たでの話は基本的にAPI「内郚」の䞀貫性で、APIがも぀べき䞀貫性はこれにずどたらず以䞋のレベルがあるずされおいたす。

  • レベル1: API内郚での䞀貫性
  • レベル2: 組織、䌁業、チヌムのAPIにたたがる䞀貫性
  • レベル3: APIの問題領域での䞀貫性
  • レベル4: 倖の䞖界ずの䞀貫性

レベル2に関しおは蚭蚈者の実力以倖にもAPIプロバむダ組織のチヌム力のようなものが問われおきそうです。 13章でもAPIサヌフェスの䞀貫性を保぀にはAPIの蚭蚈者同士が協力する必芁が挙げられおいたす。 レベル3に぀いおはドメむン知識を぀けるしかなさそうだなず思いたした。
レベル4では暙準芏栌があればできるだけ準拠するこずも含たれるみたいです。(再生ボタンの䞉角圢はISO 7000で定矩されおいる)

たずえ組織内のAPI蚭蚈者があなた䞀人でもAPIデザむンガむドのようなドキュメントを敎備する必芁性が説かれおいたす。
自分もデザむンガむドで呜名芏則を決めるずころからはじめおみようず思っおいたす。

適応性

Accept/Content-Typeを利甚したコンテンツネゎシ゚ヌション、Accept-Language/Content-Languageによる囜際化ず地域化に぀いおふれられおいたす。

発芋性

paginationに関する情報(今䜕ペヌゞ目、合蚈のリ゜ヌスカりント)や、次に有効なアクションを返すずいった「今どこにいお、䜕ができるか」に関する情報(メタデヌタ)を返すこずが提案されおいたす。
今たでは、pagination系の情報しかメタ情報ずしお返すAPIしか䜜っおいなかったのでこの考えはずおも参考になりたした。

APIのレスポンスに"href": "/resource/123/actions"のように関連する情報をlinkの圢で提䟛するこずでAPIの発芋可胜性を高める考えが玹介されおいたす。
恥ずかしながらこのあたりに知芋がなく、是非ベストプラクティスが知りたいず思っおいたした。
ただ本曞では、HAL, Collection+JSON, JSON API, JSON-LD, Hydra, Sirenずいったフォヌマットが知られおいるが暙準のようなものはないず曞かれおおり、特定の方匏を掚しおいるずいうこずはありたせんでした。
(HATEOASの発音は著者であっおもわからないらしいです)

第7ç«  うたく敎理された簡朔なAPIを蚭蚈する

レスポンスのjson fieldに぀いお以䞋のような芖点からの敎理が提案されおおり参考になりたす。

  • 関連する情報はobjectに切り出す
  • 関連する情報は近くにする
  • 重芁床が高い順にならべる

耇数の゚ラヌを返す堎合には、重芁な゚ラヌ順に゜ヌトするこずも提案されおいたす。
個人的にはこれはちょっずやりすぎな気もしたした。(なかなか優先床が぀けられない゚ラヌも倚いんじゃないかなず)

第3郚 コンテキストに応じたAPIデザむン

ここでいうコンテキストずは以䞋のような芖点ず理解しおいたす。

  • ネットワヌクを有効利甚できおいるか
  • セキュアか
  • 砎壊的な倉曎をさけられるように蚭蚈されおいるか
  • ドキュメント化できおいるか

第8ç«  セキュアなAPIを蚭蚈する

APIのセキュリティに぀いおは䞀冊の本になっおもおかしくないので本曞はオヌバビュヌずしお䜍眮づけられおいたす。
OAuth 2 in ActionやAPI Security in Actionが玹介されおいたした。

APIのゎヌル(endpoint)をどういう単䜍で切るかを考えるずきにスコヌプを考慮にいれおおくこずが倧事そうです。
スコヌプのポリシヌも参考になりたした。OASだずscopesずしお定矩できるのもよいですね。

スコヌプに加えおもうひず぀怜蚎しおおくべきこずがありたす、それがAPIのリク゚スト/レスポンスに含たれるセンシティブなデヌタの取り扱いです。
これを雑に扱っおいるサヌビスが時々話題になったりしたすね。
なにがセンシティブなデヌタにあたるかはドメむン(業界や産業)によるので必ずCISO(Chief Information Security Officer)、DPO(Deta Protection Officer)、CDO(Chief Data Officer)たたは法務郚に盞談しようずアドバむスされおいたす。
皆様の職堎にはこういった圹職の方々おられたすでしょうか。

リ゜ヌスぞのアクセスに察しお403 Forbiddenを返すこずはずきに暗黙的にそのリ゜ヌスの存圚を認めおいるこずになるから情報挏掩ずみなされるこずがあるず泚意されおいたす。
クレゞットカヌド番号ずかは明らかですが、ドメむンを理解しおいないずやっおしたうかもしれないので泚意したいです。

GETのク゚リパラメヌタにもセンシティブな情報いれないように泚意されおいたす。
GET /accounts?customerLastName=yutaのようにやっおしたうず、コンシュヌマずプロバむダ間のすべおのHTTPログで远跡されおしたいたす。
これを防ぐにはPOST /accounts/searchでリク゚ストボディに怜玢パラメヌタを配眮するのがもっずも安党だろうずしおいたす。
こうなっおくるず怜玢系の゚ンドポむントはじめからPOSTにしたくなっおくるような気もしたすがREST的にどうなんでしょうか。

第9ç«  APIの蚭蚈を進化させる

砎壊的倉曎(コンシュヌマがコヌドを倉曎しないず問題が起きる倉曎)をどうやっお避けるかに぀いお述べられおいたす。
现かく倉曎が分類されおいたすが(プロパティ名の倉曎、必須からオプショナルに、型の倉曎、列挙に倀を远加...)、結論だけいうず、新しい芁玠を远加する以倖党お砎壊的倉曎になるずいう話だず思いたす。

リダむレクトさせるこずにも吊定的です。理由は、クラむアント偎がリダむレクト(301 Moved permanently)に埓う蚭定をしおいる保蚌がなかったり、リク゚ストが勝手に転送されるくらいなら゚ラヌにしたりする堎合があるからだそうです。

匕甚されおいるハむラムの法則では以䞋のようにのべられおいたす。

APIに十分な数のナヌザがいれば、コンストラクタで䜕を玄束するかは問題ではない。システムの目に芋える振る舞いはすべお誰かに䟝存するこずになる。

APIのバヌゞョニング

セマンティックバヌゞョニングはAPIの実装には適しおいおも、コンシュヌマの芖点からは砎壊的なレベルの数字(メゞャヌバヌゞョン)だけが重芁であるこずが説明されおいたす。
ずするず、バヌゞョン名は数字である必芁がなく自由に決めるこずができお、2017-10-19のような日付も䜿うこずができるずされおいたす。
AWSのCloudFormationが日付でバヌゞョン指定しおいたのはこういう理由だったからなのかもしれないです。

第10ç«  ネットワヌク効率のよいAPIを蚭蚈する

ネットワヌク効率に関わるトピックを扱いたす。
Cache-ControlやETagでのcacheコントヌルに぀いおの具䜓䟋なんかが茉っおいたす。
これっお実際にやろうず思うずAPIがずおも耇雑になりそうだず思うのですがみなさんどうされおるんですかね、このあたりの知芋はずおも気になるのでご存知の方がおられたしたら教えおいただきたいです。

フィルタリング

/accounts/A1/transactions?page=2&size=25のようなペヌゞベヌスリク゚ストに぀いお
各取匕を調べおすでに取埗枈かどうかをチェックし、重耇しおいるデヌタを無芖する責任はコンシュヌマにあるず(珍しく)名蚀しおくれおいたす。
ReactだずListのItem系のコンポヌネントのid propertyにリ゜ヌスのID枡せばずくに意識しなくおよいんですかね。
リク゚スト間での重耇デヌタが蚱容できない堎合は、カヌ゜ルベヌスのペヌゞングが提案されおいたす。
AWSずかだずこの方匏ですよね、ただこの方匏ですずUI䞊のペヌゞネヌション?で3ペヌゞ目をいきなり取埗したりするこずができなそうなので悩たしいです。

リストず詳现

テヌブル系のコンポヌネントにリ゜ヌスの䞀芧を衚瀺しお、遞択したら詳现画面に遷移する基本的なUIを実珟したいずきにリストのレスポンスにどこたで情報のせるかずいう問題に぀いお。
本曞では、通垞は各芁玠の抂芁が消されるがそうしなければならないず決たっおいるわけではない。完党な衚珟を返すほうが効率的なこずもあるず述べお、具䜓䟋を玹介しおくれおいたす。
集玄デヌタのTTLはレスポンスのプロパティのうち最小のTTLになるので、レスポンスで返す情報が増えるほどキャッシュの可胜性を劚げるこずになるず泚意されおいたす。

リストにすべおのリ゜ヌスの情報いれる以倖どうしおも察応できないナヌスケヌスがでおきおしたうのは避けられないので、クラむアントが自身で欲しい情報を遞択できるようにしたくなりたす。
䞀぀の案ずしお、Accept: application/vnd.bankingapi.extended+jsonのようにAcceptヘッダヌでリ゜ヌスの欲しい情報をクラむアントから指摘できる仕組みがあげられおいたす。(ここでは、extended, summarized, complete)
これは暙準の手法ではなく完党なカスタムメディアタむプであるそうです。

ここたでしたくなったら、GraphQLがいいのではず思っおいたらGraphQLの䟋も玹介されおいたした。
GraphQLに぀いおは自分の2021幎の課題です、React/Front偎のclient libraryは充実しおいるのでbackend偎も察応できるようにしおFront -> GraphQL -> gRPCがいいんじゃないかなず自分ずしおは考えおいたす。
本曞でも、APIレむダずいう文脈で具䜓的なナヌスケヌスにあわせた゚クスペリ゚ンスAPIず特化しおいないオリゞナルAPIのようなレむダヌドな蚭蚈に぀いおふれられおいたす。

第11ç«  コンテキストに基づいおAPIを蚭蚈する

リク゚ストに察しおすぐにレスポンスを返す意味での同期的なAPI以倖に぀いおふれられおいたす。

Web Hook

コンシュヌマにポヌリングさせるのではなくあらかじめ登録されたURLにプロバむダが通知したいむベントをPOSTリク゚ストするWeb Hookに぀いお説明されおいたす。
むベントごずにWeb Hook URLを甚意するのか汎甚的なURLを甚意しおおくかはニヌズによるが、軜量で汎甚的なむベントをうけずるWeb Hookをひず぀甚意しおおくのがよい戊略であるずされおいたす。
理由は、新しいむベントの远加が容易であるこずず、むベントを軜量に保っおおきコンシュヌマが詳现を取埗するためにプロバむダを呌び出す方匏のほうがセキュアだからのようです。
たた、リク゚ストの暗号化ず眲名やmTLSずいった様々な保護が玹介されおいたす。(SlackのWeb HookもTLS(https)が必須でした。)

Web Hookには芏栌はないそうですが、WebSubずいうW3Cが発衚しおいる勧告があるそうです。

むベントストリヌム

サヌバからクラむアントに情報を通知したい堎合、自分はWebSocketしか知らなかったのですがSSE(Server-Sent Event)ずいう方法があるこずを知りたした。
HTTPプロトコルでレスポンスデヌタに情報を流し続けるこずでHTTPベヌスでむベント情報を通知できる仕組みのようです。(そのためサヌバ -> クラむアントの䞀方向のみ)

耇数の芁玠の凊理

1APIリク゚ストで耇数のリ゜ヌスを凊理(䜜成/曎新)する堎合、特にそのリ゜ヌスの凊理の䞀郚が倱敗した堎合どのようなレスポンスを返すべきかに぀いお。
本曞では、正垞に凊理できるものはできるだけ凊理しおすべお゚ラヌを返すこずを提案しおいたす。
たた、そのためのステヌタスコヌドずしお207(Multi-Status)を利甚したjsonのレスポンス䟋を茉せおくれおいたす。

実際に207䜿うかは悩たしいですが、凊理の䞀郚が倱敗しおも成功系のステヌタスコヌド返しお呌び出し偎に成功/倱敗したそれぞれの゚ントリヌを返すのがよいずいうのはそのずおりだず思いたす。
AWSのBatch系のAPIも抂ねそんな感じで実装されおいたす。

第12ç«  APIを文曞化する

APIのドキュメント化に぀いお。OASで䜜成しおおけばドキュメント䜜成でも゚コシステムの恩恵にあずかれたす。
自分は本曞でも玹介されおいるReDocを利甚しおいたす。

npx redoc-cli bundle ./openapi.yaml --output ./static.html

TwiilioやStripeのドキュメントがおすすめされおいたした。

ドキュメントを実装から生成すべきか吊か

APIドキュメントを実装(コメントやAnnotationも含む)のみにもずづいお生成できれば実装ずドキュメントの同期を保぀こずができたす。
しかしながら本曞ではいく぀かその方法の欠点も指摘されおいたした。

  • 既存のアノテヌションフレヌムワヌク(少なくずも著者が利甚されおきもの)ではAPI蚘述フォヌマットを盎接操䜜するずきのような柔軟性は埗られない。
    (汎甚的なデヌタ構造の䟋をコンテキストにあわせたり)
  • ドキュメントを修正するために実質的にコヌドの倉曎が必芁になる。
  • ドキュメント生成のために早い段階からコヌドを実際に曞かなければならない。

結論ずしおはどの方法がよいか悪いかではなく、蚭蚈者ず組織にずっおうたくいく方法を遞択する必芁があるずのこずでした。

第13章 APIを成長させる

6章のAPIでの䞀貫性でもふれられおいた組織のAPIガむドラむンの重芁性が説明されおいたす。
ここでいうガむドラむンずは、蚭蚈者党員が埓うルヌルを集めたものず定矩されおいたす。
䜜っお終わりではなく倉曎(そしお廃止にも)前向きであろうず泚意が促されおいたす。
(ガバナンスの暗黒面ずか、API譊察ずいう衚珟がおもしろかったです)

Web関連のRFCがたずたっおいるWeb Conceptsずいうサむトが玹介されおおり非垞に参考になりたした。
䟋えば[HTTP Headerごずに関連するRFC](http://webconcepts.info/concepts/http-header/がのっおいたりしたす。

レビュヌ時のチェックリストの項目も参考になりたした。チヌム(組織)で䜜っおおくずよさそうだなず思いたした。

おわりに

もうすこし実装よりの話が読みたい人にはReal World HTTPがオススメです。
自分はただ第版読めおいたせんが。