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

公開: 2022-03-11

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

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

視点

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

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

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

まあ、あなたは確かに彼らの視点を理解していますが、あなたは必ずしも彼らの視点を共有しているわけではありません。 APIを開発または拡張する場合、APIデザイナーの視点がありますが、APIユーザーの視点があります。

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

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

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

それでは、先に進んで、優れたWebAPIを設計するための5つのゴールデンルールについて説明しましょう。

  1. ドキュメンテーション
  2. 安定性と一貫性
  3. 柔軟性
  4. 安全
  5. 採用のしやすさ
関連： REST仕様でこれまでに行ったことのない5つのこと

ルール1：文書化

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

関連： Grape Gemチュートリアル：RubyでRESTのような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トークンをPOST変数として、または「Authorization：da39a3ee5e6b4b0d3255bfef95601890afd80709」などの形式のヘッダーとして送信できます（送信する必要があります）。

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

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

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

覚えておくべき他のいくつかの重要な事柄があります：

  • ホワイトリスト機能。 APIを使用すると、通常、データに対して基本的な作成、読み取り、更新、および削除の操作を実行できます。 ただし、すべてのエンティティに対してこれらの操作を許可する必要はないため、それぞれに許可されるアクションのホワイトリストがあることを確認してください。 たとえば、許可されたユーザーのみが/user/delete/<id>などのコマンドを実行できることを確認してください。 同様に、ユーザーのリクエストで送信されるすべての有用なヘッダーも、ホワイトリストに対して検証する必要があります。 コンテンツタイプのヘッダーを許可する場合は、ユーザーが送信するものが、サポートされているコンテンツタイプのwhileリストと実際に一致することを確認してください。 そうでない場合は、406NotAcceptable応答などのエラーメッセージを送り返します。 ホワイトリストは、多くのAPIが自動的に生成されるか、代わりにブラックリストを使用するため重要です。つまり、不要なものについて明示的にする必要があります。 ただし、セキュリティの黄金律は、まったく何もないところから始めて、必要なものだけを明示的に許可することです。

  • クロスサイトリクエストフォージェリ（CSRF）から身を守りましょう。 セッション認証またはCookie認証を許可している場合は、CSRF攻撃から身を守っていることを確認する必要があります。 Open Web Application Security Project（OWASP）は、これらの脆弱性を排除する方法に関する有用なガイダンスを提供します。

  • リソースへのアクセスを検証します。 すべてのリクエストで、ユーザーが参照している特定のアイテムへのアクセスが実際に許可されていることを確認する必要があります。 したがって、ユーザーのクレジットカードの詳細を表示するエンドポイント（たとえば、 /account/card/view/152423 ）がある場合は、ID「152423」がユーザーが実際にアクセスを許可されているリソースを参照していることを確認してください。

  • すべての入力を検証します。 ユーザーからのすべての入力は安全に解析する必要があります。XMLやJSONなどの複雑な入力を使用している場合は、よく知られたライブラリを使用することをお勧めします。 独自のパーサーを作成しないでください。そうしないと、傷ついた世界に陥ります。

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

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

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

  • 人々が実際にあなたのAPIを使用できること、そしてそれが毎回初めて機能することを確認してください。 新しい人々に時々あなたのAPIを実装してもらい、あなたが免疫を持っていることを何らかの方法で混乱させていないことを確認してください。

  • 単純にする。 派手な認証は行わないでください。 クレイジーなカスタムURLスキームを実行しないでください。 SOAP、JSON、RESTなどを再発明しないでください。 すでに実装され広く受け入れられている可能なすべてのツールを使用して、開発者がAPIを学習するだけでよく、API+10のあいまいな新しいテクノロジーを学習する必要はありません。

  • サービスとインターフェイスするための言語固有のライブラリを提供します。 AlpacaやApacheThriftなど、ライブラリを自動的に生成するための優れたツールがいくつかあります。 現在、AlpacaはNode、PHP、Python、Rubyをサポートしています。 Thriftは、C ++、Java、Python、PHP、Ruby、Erlang、Perl、Haskell、C＃、Cocoa、JavaScript、Node.js、Smalltalk、OCaml、Delphiなどをサポートしています。

  • 必要なサインアップを簡素化します。 オープンソースAPIを開発していない場合、または何らかの種類のサインアッププロセスがある場合は、サインアップ時にユーザーが非常に迅速にチュートリアルに誘導されることを確認してください。 また、ユーザーの操作を必要とせずに、サインアッププロセスを完全に自動化します。

  • 優れたサポートを提供します。 採用の大きな障壁は、サポートの欠如です。 バグレポートをどのように処理して対応しますか？ 不明確なドキュメントはどうですか？ 洗練されていないユーザー？ フォーラム、バグトラッカー、および電子メールサポートは素晴らしいスタートですが、誰かがバグを投稿したときに、あなたが本当にそれに対処することを確認してください。 ゴーストタウンのフォーラムや、対処されていないバグの巨大なリストを見たいと思う人は誰もいません。

WebAPIのまとめ

WebサービスとそのAPIはたくさんあります。 残念ながら、大多数は使用が困難です。 理由は、不十分な設計、ドキュメントの欠如、不安定さ、未解決のバグ、または場合によっては上記のすべてにまで及びます。

この投稿のガイダンスに従うと、Web APIがクリーンで、十分に文書化され、使いやすいことを確認するのに役立ちます。 このようなAPIは非常にまれであるため、広く採用され、使用される可能性がはるかに高くなります。

関連：ソフトウェアのプライベートAPIをリバースエンジニアリングするためのチュートリアル：ソファのハッキング