Webフロントエンド

優れたWebAPI設計のための5つのゴールデンルール

疑問に思ったことはありませんか 「彼らは何を考えていたのですか？」 APIを介してWebサービスを統合する場合はどうなりますか？そうでなければ、あなたは私よりはるかに幸運でした。

ソフトウェア開発者なら誰でも、プロジェクトをスパゲッティコードに移行させるのがいかに簡単かを知っています。また、Web APIは、Webが絡み合う傾向があります。しかし、そのようにする必要はありません。実は、デザインすることは可能です すごい 人々が実際に行うWebAPI 楽しい を使用して、作成もお楽しみいただけます。しかし、どのように？その質問への答えは、この投稿が何であるかです。

展望

ほとんどの場合、ソリューションを構築するときは、プログラマーではない、または一般的に技術的に洗練されていないエンドユーザー向けに設計します。あなたは彼らにグラフィカルインターフェースを提供していて、あなたが正しく仕事をしているなら、あなたは彼らがインターフェースをするために何を必要としているかについて彼らからかなり良いアイデアを集めました。

だが API開発違います。のインターフェースを設計しています プログラマー 、おそらく彼らが誰であるかさえ知らずに。そして、彼らが誰であろうと、彼らはあなたのソフトウェアのあらゆる小さな欠陥を指摘するための技術的な洗練を持っているでしょう（または少なくとも彼らは技術的な洗練を持っていると思うでしょう）。あなたのユーザーはあなたが彼らのものと同じようにあなたのAPIに批判的である可能性が高く、それを批評することを完全に楽しむでしょう。

ちなみに、そこには皮肉の一部があります。場合 誰でも 使いやすいWebAPIを作成する方法を理解する必要があります。君は。結局のところ、あなたはAPIのユーザーと同じようにソフトウェアエンジニアなので、彼らの視点を共有します。ね？

まあ、あなたは確かに 理解する 彼らの視点、あなたは必ずしも シェア 彼らの視点。開発または強化するとき君の API、あなたはAPIの視点を持っています デザイナー 一方、APIの観点があります ユーザー 。

APIデザイナー 通常、次のような質問に焦点を当てます 「このサービスは何をする必要がありますか？」 または 「このサービスは何を提供する必要がありますか？」 、ながら APIユーザー に焦点を当てています 「このAPIを使用して必要なことを行うにはどうすればよいですか？」 、より正確には、 「このAPIから必要なものを取得するために、最小限の労力をどのように費やすことができますか？」 。

これらの異なる質問は、2つの大きく異なる視点につながります。その結果、設計に必要な前提条件 すごい APIは、APIデザイナーの視点からAPIユーザーの視点に視点を移すことです。言い換えれば、あなたがあなた自身のユーザーであるならばあなたが自然に尋ねるであろう質問を絶えずあなた自身に尋ねてください。 APIについて考えるのではなく できる する必要がある、またはなりたいと思うさまざまな方法について考えてください中古次に、APIのユーザーがこれらのタスクをできる限り簡単にすることに重点を置きます。

これは簡単で明白に聞こえるかもしれませんが、APIがこのように設計されていることはめったにないように見えるのは驚くべきことです。キャリアの中で遭遇したAPIについて考えてみてください。この観点を念頭に置いて設計されたように見える頻度はどれくらいですか？ WebAPIの設計は難しい場合があります。

それでは、先に進んで、 優れたWebAPIを設計するための5つのゴールデンルール 、すなわち：

ドキュメンテーション
安定性と一貫性
柔軟性
セキュリティ
採用のしやすさ

関連： REST仕様でこれまでに行ったことのない5つのこと

ルール1：文書化

ドキュメンテーション。はい、ここから始めます。

ドキュメントが嫌いですか？共感することはできますが、「ユーザーの視点」を身に付けてください。ドキュメントを作成するよりも嫌いなことの1つは、ドキュメント化されていないAPIを使用することです。私は私の場合を休ませます。

肝心なのは、誰かにAPIを使用してもらいたい場合は、ドキュメントが不可欠であるということです。これを正しく行う必要があります。これはユーザーが最初に目にするものなので、ある意味ではギフト包装のようなものです。うまく提示すれば、人々はあなたのAPIを使用して、どんな特異性にも我慢する可能性が高くなります。

では、どのようにして優れたドキュメントを作成するのでしょうか。

比較的簡単な部分は、APIメソッド自体を文書化することです。つまり、リクエストとレスポンスの例、および両方の各要素の説明。幸いなことに、ドキュメントを生成するタスクを容易にし、簡素化するソフトウェアツールの数が増えています。または、API、エンドポイント、関数をイントロスペクトし、対応するドキュメントを生成するものを自分で作成することもできます。

ゲシュタルト理論を説明し、例を引用する

しかし、優れたドキュメントと適切なドキュメントを区別するのは、使用例と、理想的にはチュートリアルが含まれていることです。これは、ユーザーがAPIとどこから始めればよいかを理解するのに役立ちます。それは彼らを方向付け、彼らがあなたのAPIを彼らの脳にロードするのを助けます。

たとえば、の開発者が Twilio すべてのクラス、すべてのメソッド、およびAPIに対するすべての可能な応答をリストすることでしたが、APIを介してSMSを送信したり、通話を追跡したり、電話番号を購入したりできることは言うまでもありませんでした。 APIユーザーがその情報を見つけて、それをまとまって理解するのに長い時間がかかります。名前以外に、それらが何のために使用されたかについての洞察なしに、クラスとメソッドの巨大なツリーをソートすることを想像できますか？ひどいですね。しかし、それはまさに多くのAPIプロバイダーが行っていることであり、そのため、APIは自分以外の誰にも不透明なままになっています。ザ・ RackspaceCloudFiles開発者およびAPIガイドそのような例の1つです。彼らが何をしていて何を提供しているのかをすでに理解していない限り、あなたの方向性を理解することは困難です。

したがって、開発者がやろうとしていることのスケルトンを少なくとも含めて、開発者を迅速に立ち上げて実行するのに役立つ簡潔なチュートリアルを作成し、拡張できるように、より詳細で完全に文書化された機能のリストの方向に向けます。彼らが持っているものについて。

ドキュメントが完成したら、自分以外の人にとって意味があることを必ず確認してください。ネットワーク内の他の開発者に送信し、ドキュメントを参照する以外に指示を与えず、チュートリアルに従うか、約15分で本当に基本的なものを作成するように依頼します。 15分以内にAPIと基本的な統合ができない場合は、さらに作業が必要です。

優れた詳細なドキュメントのいくつかの注目すべき例については、チェックアウトしてください Twilio 、 Django 、および MailChimp 。これらの製品はどれも必ずしも市場で最高のものではありませんが（すべて優れた製品ですが）、市場内で最高のドキュメントを提供することでテーマを区別し、幅広い受け入れと市場シェアを確実に促進しています。

ルール2：安定性と一貫性

使用したことがある場合 FacebookのAPI 、APIが非推奨になり、完全に書き直される頻度をご存知でしょう。あなたが彼らのハッカー文化や彼らの製品をどれほど尊重しても、彼らは開発者に優しい視点ではありません。彼らがまだ成功している理由は、APIが優れているからではなく、10億人のユーザーがいるからです。

しかし、おそらくそのような巨大なユーザーベースと市場シェアの贅沢はないので、古いバージョンを実行し続け、かなり長期間サポートする、はるかに揮発性の低いAPIが必要になります。多分何年も。そのために、ここにいくつかのヒントとコツがあります。

たとえば、APIにURL http://myapisite.com/api/widgetsを介してアクセスできるとします。そして、JSON形式でその応答を提供します。これは一見問題ないように見えるかもしれませんが、JSON応答の形式を変更する必要がある場合はどうなりますか？すでにあなたと統合されているすべての人が壊れます。おっと。

したがって、事前に計画を立て、APIを最初からバージョン管理し、バージョン番号をURLに明示的に組み込んで（たとえば、http://myapisite.com/api/widgets?version=1またはhttp://myapisite.com/api/widgets/v1）、ユーザーがバージョン1の動作に依存して、にアップグレードできるようにします。準備ができた後のバージョン。ある時点で以前のバージョンを段階的に廃止する必要がある場合は、先に進んでください。ただし、十分な通知を行い、何らかの移行計画を提示してください。

優れたURLスキームでは、URLにメジャーバージョンが含まれます。出力形式またはサポートされているデータ型を変更すると、新しいメジャーバージョンにバンプアップするはずです。一般に、出力にキーまたはノードを追加するだけの場合は同じバージョンを維持できますが、安全のために、出力が変更されるたびにバージョンをバンプしてください。

APIは長期にわたって安定していることに加えて、内部的に一貫している必要があります。使用されているエンドポイントに応じて、パラメータ名やPOSTデータのメソッドを変更する多くのAPIを見てきました。代わりに、API内で共通のパラメーターをグローバルに処理し、継承または共有アーキテクチャを使用して、API全体で一貫して同じ命名規則とデータ処理を再利用する必要があります。

最後に、変更ログを記録して公開し、APIのバージョン間の違いを示して、ユーザーがアップグレード方法を正確に把握できるようにする必要があります。

ルール3：柔軟性

ガベージイン、ガベージアウト（GIGO）これは、ほとんどのプログラマーによく知られているマントラです。 Web API設計に適用される場合、このガイド原則は、検証を要求するためのかなり厳格なアプローチを指示する傾向があります。いいですね。混乱も問題もありません。

しかし、すべての場合と同様に、ある程度のバランスが必要です。ユーザーがあなたのサービスを利用したいと思うすべての方法を予測することは不可能であり、すべてのクライアントプラットフォームが一貫しているわけではないため（つまり、すべてのプラットフォームが非常に優れたJSONサポート、適切なOAuthライブラリなどを備えているわけではない）、入力と出力の制約に関して、少なくともある程度の柔軟性または許容範囲があります。

たとえば、多くのAPIは、JSON、YAML、XMLなどのさまざまな出力形式をサポートします。 al。ですが、URL自体でのフォーマットの指定のみをサポートします。柔軟性を維持するという精神で、これをURL（/api/v1/widgets.jsonなど）でも指定できるようにすることも、Accept: application/jsonを読んで認識することもできます。 HTTPヘッダー、または?format=JSONなどのクエリ文字列変数をサポートします。

そして、私たちがそれに取り組んでいる間、ユーザーが?format=jsonを指定できるように、指定された形式で大文字と小文字を区別しないようにしないのはなぜですか。同じように？これは、APIのユーザーの不必要な欲求不満を軽減する方法の典型的な例です。

別の例は、変数を入力するさまざまな方法を可能にすることです。したがって、さまざまな出力形式があるのと同じように、さまざまな入力形式も許可します（たとえば、プレーンPOST変数、JSON、XMLなど）。少なくとも標準のPOST変数をサポートしている必要があり、最近の多くのアプリケーションはJSONもサポートしているため、これら2つから始めるのが適切です。

ここでのポイントは、誰もがあなたの技術的な好みを共有していると思い込んではいけないということです。他のAPIがどのように機能するかを少し調べて、他の開発者との対話を通じて、有用な他の価値のある代替案を収集し、それらをAPIに含めることができます。

ルール4：セキュリティ

セキュリティは明らかにWebサービスに組み込むための最も重要なものの1つですが、非常に多くの開発者がそれを途方もなく使いにくくしています。 APIプロバイダーとして、APIにアクセスするときに認証および承認する方法の有用な例を提供する必要があります。これは、エンドユーザーが何時間もかけて作業する難しい問題ではありません。コードを書く必要がないか、コードを書くのに5分もかからないことを目標にします。

ほとんどのAPIの場合、私は単純なものを好みますトークンベースの認証、トークンはユーザーに割り当てられたランダムハッシュであり、盗まれた場合はいつでもリセットできます。トークンがPOSTまたはHTTPヘッダーを介して渡されることを許可します。たとえば、ユーザーは送信できます（送信する必要があります）。 SHA-1 token POST変数として、または「Authorization：da39a3ee5e6b4b0d3255bfef95601890afd80709」などの形式のヘッダーとして。

また、短い数値識別子ではなく、安全なトークンを選択してください。不可逆的なものが最善です。たとえば、ユーザーの作成中にSHAトークンを生成し、それをデータベースに保存するのは比較的簡単です。次に、そのトークンに一致するユーザーをデータベースに照会するだけです。また、SHA(User.ID + 'abcd123')のように、一意の識別子とソルト値で生成されたトークンを実行して、一致するユーザーをクエリすることもできます。例：where TokenFromPost = SHA(User.ID + 'abcd123')。

別の非常に良いオプションは OAuth 2 + SSL 。とにかくSSLを使用する必要がありますが、OAuth 2はサーバー側で実装するのがかなり簡単であり、ライブラリは多くの一般的なプログラミング言語で利用できます。

作成したAPIがJavaScriptを介して公開Webサイトでアクセス可能であると想定されている場合は、トークンのアカウントごとのURLのリストも検証する必要があります。そうすれば、誰もAPIの呼び出しを調べて、ユーザーからトークンを盗み、それを自分で使用することはできません。

覚えておくべき他の重要な事柄は次のとおりです。

ホワイトリスト機能。 APIを使用すると、通常、データに対して基本的な作成、読み取り、更新、および削除の操作を実行できます。ただし、すべてのエンティティに対してこれらの操作を許可する必要はないため、それぞれに許可されるアクションのホワイトリストがあることを確認してください。たとえば、許可されたユーザーのみが/user/delete/などのコマンドを実行できることを確認してください。同様に、ユーザーのリクエストで送信されるすべての有用なヘッダーは、ホワイトリストに対しても検証する必要があります。コンテンツタイプのヘッダーを許可する場合は、ユーザーが送信するものが、サポートされているコンテンツタイプのwhileリストと実際に一致することを確認してください。そうでない場合は、406 NotAcceptable応答などのエラーメッセージを返送してください。多くのAPIが自動的に生成されるか、代わりにブラックリストを使用するため、ホワイトリストは重要です。つまり、自分が何をしているのかを明確にする必要があります。 しないでください 欲しいです。ただし、セキュリティの黄金律は、まったく何もないところから始めて、明示的に許可することだけです。行う欲しいです。
javascriptの日付を文字列に変更
から身を守るクロスサイトリクエストフォージェリ（CSRF）。 セッション認証またはCookie認証を許可している場合は、CSRF攻撃から身を保護していることを確認する必要があります。ザ・オープンWebアプリケーションセキュリティプロジェクト（OWASP）に役立つガイダンスを提供しますこれらの脆弱性を排除する方法。
リソースへのアクセスを検証します。 すべてのリクエストで、ユーザーが参照している特定のアイテムへのアクセスが実際に許可されていることを確認する必要があります。したがって、ユーザーのクレジットカードの詳細を表示するエンドポイント（/account/card/view/152423など）がある場合は、ID「152423」がユーザーが実際にアクセスを許可されているリソースを参照していることを確認してください。
すべての入力を検証します。 ユーザーからのすべての入力は安全に解析する必要があります。XMLやJSONなどの複雑な入力を使用している場合は、よく知られたライブラリを使用することをお勧めします。独自のパーサーを作成しないでください。そうしないと、傷ついた世界に陥ります。

ルール5：採用のしやすさ

これは本当に最も重要なルールであり、他のすべてのルールに基づいています。ドキュメントルールで述べたように、APIを初めて使用する人と一緒にこれを試してみてください。チュートリアルに従っている場合でも、数分以内に、少なくともAPIの基本的な実装で稼働できることを確認してください。 15分が良い目標だと思います。

APIの採用を容易にし、促進するための具体的な推奨事項は次のとおりです。

人々が実際にあなたのAPIを使用できること、そしてそれが毎回初めて機能することを確認してください。 新しい人にAPIの実装をときどき試してもらい、それが何らかの形で混乱していないことを確認します。
複雑にしないでおく。 派手な認証は行わないでください。クレイジーなカスタムURLスキームを実行しないでください。 SOAP、JSON、RESTなどを再発明しないでください。すでに実装され、広く受け入れられているツールをすべて使用してください。そうすれば、開発者はAPIを学ぶだけでよく、API +10のあいまいな新しいテクノロジーを学ぶ必要はありません。
サービスとインターフェイスするための言語固有のライブラリを提供します。 ライブラリを自動的に生成するための優れたツールがいくつかあります。アルパカまたは ApacheThrift 。現在、AlpacaはNode、PHP、Python、Rubyをサポートしています。 Thriftは、C ++、Java、Python、PHP、Ruby、Erlang、Perl、Haskell、C＃、Cocoa、JavaScript、Node.js、Smalltalk、OCaml、Delphiなどをサポートしています。
必要なサインアップを簡素化します。 オープンソースAPIを開発していない場合、または何らかのサインアッププロセスがある場合は、サインアップ時にユーザーがチュートリアルにすばやく誘導されることを確認してください。また、ユーザーの操作を必要とせずに、サインアッププロセスを完全に自動化します。
優れたサポートを提供します。 採用の大きな障壁は、サポートの欠如です。バグレポートをどのように処理して対応しますか？不明確なドキュメントはどうですか？洗練されていないユーザー？フォーラム、バグトラッカー、および電子メールサポートは素晴らしいスタートですが、誰かがバグを投稿したときに、本当にそれに対処するようにしてください。ゴーストタウンのフォーラムや、対処されていないバグの膨大なリストを見たいと思う人は誰もいません。