REST API設計ガイドライン

Posted: 2016/07/20 カテゴリー: Uncategorized
タグ:, , , ,

MicrosoftがAPIコミュニティに「REST API設計ガイドライン」(https://github.com/microsoft/api-guidelines/)を公開することを発表できて、嬉しく思います。

このガイドラインは、Microsoftの世界規模のクラウド サービスの設計、運用、稼働を行い、お客様やパートナーからの我々のAPIへのフィードバックに耳を傾けている、数百人のエンジニアの集合体験を集約した、複数年にわたる企業横断的な協力プロセスを象徴しています。我々は、MicrosoftのAPIチームが日常的に使うガイドラインを作成するために、API領域の業界のベスト プラクティスとともに、これらの学びを組み込もうと試みました。

このガイドラインのより幅広いAPIコミュニティへの公開で、我々が期待していることが2つあります。

  • まず、我々のAPIとそれを構築する我々のアプローチへのフィードバックをさらに刺激することを、期待しています。我々は、このようなフィードバックを通してのみ、進化しつつあるお客様のニーズに合った製品を構築できます。
  • そして、我々は、自らのガイドラインを共有したAPI設計コミュニティの他のメンバーから恩恵を受けてきたので、我々は貢献し返したいのです。ほとんどどんな規模の組織であっても、APIを構築している組織は自らの設計ガイドラインを持つことから恩恵を受けられると、我々は信じています。多くの企業やホワイトハウスのような組織でさえも、自らの設計ガイドラインをすでに公開しています。我々のガイドラインをコミュニティに公開することで、組織内で標準とガイドラインを設定しようとする際に誰もがさらなる集合知識を活用できるように、コミュニティの知識と再利用可能なコンテンツを増やすことを我々は期待しています。

API設計では物事を行う正しい方法が複数あることを、我々は認識しています (たとえば、snake-case、train_case、UpperPascalCaseなど)。Microsoftの同僚達との多くの議論の後に決まったものを、設計ガイドラインとして共有します。このガイドラインが時間とともに進化することを、我々は期待しています。

由来

当然ながら、GitHub上のMicrosoft REST APIガイドライン ドキュメントは、現在皆さんが目にしているものになる前に、多数のイテレーションを経ました。

お客様からのフィードバックの2つの要点を耳にしたことから、この取り組みが始まりました。

  • Microsoft APIでの作業の開始は、より簡単であるべきです。 – 開発者は、わずか数分で、APIエンドポイントに対してcurlツールを実行し、人間が読める結果を取得したかったのです。
  • Microsoftのクラウド サービス向けのAPIには、一貫性があるべきです。 – 開発者は、Azure Virtual Machinesを扱うAPIとOffice 365のドキュメントを扱うAPIが、企業内の別のチームによって開発されたことを気にかけませんでした。両者はMicrosoftのものなので、開発者は一貫性を期待していたのです。

この取り組みの目標の1つは、ガイドラインにおける詳細さの適切なバランスを見つけることでした。我々は、ベスト プラクティスを十分に体系化している一方で、個々のエンジニアやテクニカルプロダクト/プログラムマネージャーによって親しみやすいドキュメントを望んでいました。

ODataとの関係

OASISのオープン標準であるODataは、ワイヤレベルの相互運用性を探しているAPI開発者に、深いレベルの詳細を提供しています。MicrosoftチームはODataに従う (そして、ODataの幅広いエコシステムから恩恵を得る) ことを推奨されているものの、ODataがチームが必要としているものより具体的すぎる場合も、追加情報が必要とされる場合もありました。ずれが起こっている領域では、OASIS ODataテクニカルコミッティに情報を提供し返すために我々は作業してきており、最新のOData v4.0、OData v4.01の多くの側面には、Microsoft REST APIガイドラインの進化からの学びが組み込まれています。

Open API Initiative (OAI)との関係

Microsoftが (Swaggerの進化である) Open API Initiative (OAI) のメンバーであることを、我々は誇りに思っています。OAI/Swaggerの取り組みの対象範囲がフレームワークとツールから拡張され、仕様も含むようになってきたので、今後、Microsoftの同僚達が、両者を進化させ続けるためにOAIコミュニティに関与するさらなる機会があると、我々は信じています。

作業の開始

もしここまでお読みいただいていたら、ありがとうございます。

GitHubで、Microsoft REST APIガイドラインを入手できます (https://github.com/microsoft/api-guidelines/)。我々は皆さんからのフィードバックを歓迎しており、Issueの登録とプル リクエストを推奨しています。

このガイドラインを使って実装された我々のAPIを試したい場合は、Microsoftのクラウド サービスの集約されたエンドポイントである、Microsoft Graphを見てみることをお勧めします。http://graph.microsoft.io/ から始めてください。

皆さんからのフィードバックを楽しみにしています。

Gareth、Rob

Gareth Jones (@garethj_msft)
Principal API Architect
Applications and Services division

Rob Dolin (@RobDolin)
Senior Program Manager
Cloud and Enterprise division

コメント
  1. […] REST API設計ガイドライン […]

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト / 変更 )

Twitter 画像

Twitter アカウントを使ってコメントしています。 ログアウト / 変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト / 変更 )

Google+ フォト

Google+ アカウントを使ってコメントしています。 ログアウト / 変更 )

%s と連携中