シェア:
){kind=small}
Alyssa is a writer and editor specializing in technology and the software development space. She lives in central California with her husband, kids, and three rescue dogs.
NexmoにおけるOpenAPI主導の開発
所要時間：1 分
Nexmoでは、OpenAPI主導の開発プロセスを採用しています。その理由は以下の通りです。
歴史は、ソフトウェア開発が過度な仕様の重みで窒息することを教えてくれている。
アジャイルマニフェストの共著者、アンディ・ハント、 はこう語る。彼が1990年代に取り組んだプロジェクトの話である。2年半と数百万ドルの後、プロジェクトのアーキテクトは部屋いっぱいのUML図を作成したが、コードは1行もデプロイされなかった。
今日、私たちは、多くの場合、解決しようとしている問題の本質を発見するのは、コードを書いているときだけであるという理解と、前もっての仕様の必要性のバランスを注意深く取っている。
しかし、スペックとディスカバリーのバランスは、パブリックAPIの場合、他の種類のソフトウェアを構築する場合とは異なることがわかりました。そしてNexmoでは、新しいAPIを開発する方法を変えることになりました。新しいサービスを開発するときに最初にすることは、OpenAPI仕様を作成することです。新しいサービスを開発するときに最初にすることは、OpenAPI仕様を作成することです。これにより、開発者のエクスペリエンス、人間対機械の可読性、自動化などの利点が得られます。
APIは公開契約だ。私たちが メッセージAPIのようなものを構築して立ち上げるとき、私たちは顧客と契約することになる。
つまり、パブリックAPIを作ることは、規格を作ることと本質的に同じなのだ。SVGについて考えてみよう。ベクターグラフィックスの標準だ。標準と、その標準の様々な実装は別個のものとして存在する。もし私がSVGファイルを生成するライブラリを書けば、後でそのファイルを読むソフトウェアの実装の詳細を気にする必要はないはずだ。
あまりにも多くの場合、APIは基本的な実装によって形作られている。 リーキーな抽象化-あるいは、その場しのぎの設計上の決定によって形作られる。OpenAPI仕様の作成から始めるということは、その下で起こっていることの詳細から一歩離れた、意図的な設計上の決定を行うことができるということです。その結果、一貫性のある直感的な開発者体験が得られるのだ。
予想外の利点として、OpenAPI仕様の作成は潜在的なユーザビリティの問題を発見してくれる。OpenAPI仕様でAPIをモデル化するのが難しいということは、API自体も使いにくいということになりがちだということがわかりました。そのため、私たちは、そうでなければ製品化されたかもしれない、最適とは言えないAPIの設計を見直すことになりました。
Stoplight.ioのテイラー・バーネットは、OpenAPI仕様を次のように説明している。開発契約、チーム間の橋渡し."人間がコードを書いても、APIは明示的にマシン間のインターフェースとして機能する。
OpenAPI-spec主導の開発は、APIを単なる2つのコード間のインターフェイス以上のものにする。それはAPIを人々の間の合意ソースに変える。テクニカルライターはドキュメンテーション作業のキックスタートに、開発者の支持者は外部の開発者に説明するために、プロダクトマネージャーはAPIの機能に関する真実のソースとして維持するために、APIを使うことができる。
次のように キン・レーンによって文書化されているように、企業はAPIの設計の公開声明としてOpenAPIの仕様をGitHubに公開するようになってきている。一つのドキュメントで、APIがどのように振る舞うべきかを機械可読かつ人間可読で記述することができる。そこから、開発者は期待される動作が何であるかを確認し、APIの能力について推論することができる。
OpenAPI仕様には、あらゆる種類の自動化を可能にするという期待がある。クライアント・ライブラリ、モック・エンドポイント、テスト、ドキュメントを自動的に生成できる可能性がある。
Screenshot of API
Nexmoでは、その旅のスタート地点にいる。今日、我々はAPIリファレンスドキュメントといくつかのテストを自動生成している。特に、OpenAPIの仕様を前もって持つことで、スモークテストを作成しやすくなることがわかりました。
OpenAPIの仕様では、エラーメッセージを含むAPIの期待される入出力を定義しています。その仕様を使って、意図的に不正なデータを提供し、期待されるエラーメッセージが返されることを確認するスモークテストを自動的に生成することができます。
結局のところ、最大の利点は、OpenAPI仕様から始めることで、単一の真実のソースを手に入れることができるということだ。API設計を様々なフォーマットで、様々な場所（WikiやGoogle Docsなど）に置くのではなく、スペックは開発プロセスの標準的な一部となり、標準的な開発ツールを使って作成される。
その1つの仕様書は、開発が完了したときに自分たちや同僚に伝える手段であり、外部の開発者に何を期待すべきかを伝える手段でもある。ある意味、スペックはAPIであり、実装はそれに過ぎない。
我々はOpenAPIファーストの旅のスタート地点にいる。これまで2つのAPIでこのプロセスを試してきました。リダクトと 秘密管理-しかし、私たちのAPIはすべて、完全で公開されたOpenAPI仕様を持っており、私たちはすべての開発を仕様優先モデルに移行する予定です。
これまでの私たちの仕事から、これがより質の高いAPIの実装、時間の節約、より深い理解につながると確信しています。私たちは、これが業界全体のAPIの質をどのように向上させるかを楽しみにしています。