[訳文]APIインタフェースのより良い設計に関する8つの提案
4966 ワード
テキストリンク:http://www.coderslexicon.com/8-tips-to-a-better-api-design/
私はすでに多くのAPI設計に関する文章と優秀なREST API設計チュートリアルを見たことがあります.彼らは通常、適切な符号化技術と、所与の言語でインタフェースを露出する方法について議論します.それらは役に立つことも必要ですが、APIをよりよく機能させる考えをよく無視しています.この記事では、APIサービス会社のプロジェクトで実践した8つのアドバイスを提供します.次のプロジェクトで使用できることを望んでいます.
1.適合性と統一性を勝ち取る
ここでは,APIを予測可能に設計することが要求される.このようにして、すべてのインタフェースとインタフェースに必要なパラメータを書きます.名前が一致し、インタフェースに必要なパラメータの順序も一致していることを確認します.あなたは今products、orders、customersのデータを持っているでしょう.idとnameを含むテーブルに存在するはずです.では、1つのインタフェースにIDのみを送信させないでください.もう1つのインタフェースにはnameのみを送信し、2つのインタフェースにも送信します.1つのインタフェースを
もう1つのコンプライアンスを保証するテクニックは、パラメータ値のタイプを観察することです.一方のインタフェースのIDパラメータが整数型である場合、他方のインタフェースのIDパラメータを文字列型にしないでください.APIの使用者として、各インタフェースの各パラメータ値タイプを推測したくないからです.
インタフェースがどのようにデータにアクセスするかを考慮する必要があるほか、APIがどのようにデータを返し、データフォーマットの統一性を返すかをよく考えなければなりません.現在、私が最近使っているAPIでは大きな問題があります.開発でデータを返すインタフェースを使用すると、戻り結果(XML形式の...なぜ私がそれを避けるのかについて議論します)の各要素に特定の属性が含まれていることに驚きました.しかし、結果として、一部の要素にはその属性があり、他の要素はありません.私はむしろその属性が空の値であっても、その属性が全く見えないことを望んでいません.なぜなら、各要素を巡ってこのプロパティを探す場合は、値がなくても少なくとも見つけたいからです.しかし、データベースからいくつかのレコードを検出して、いくつかのデータの中にフィールドがなく、他のいくつかのレコードがあることを発見しました.そして、クエリーの結果を疑い、「消えた属性は私に失われたのか」という疑問を抱き始めました.
2.素直に考える
誰かに電話して何かしてもらったときに「はい!」と快く返事をした経験があるのではないでしょうか.通常、あなたはためらって「本当に手伝ってくれるの?」と聞きます.優れたAPIは、実行したい操作だけでなく、実行したばかりの操作に関する情報も追加で返されます.APIがproductの作成を担当している場合は、作成したばかりのproductに関する情報をクライアントに要求するのではなく、作成操作を実行した後に作成したばかりのproductに関する情報を返すようにします.それは君が頭が悪いように見えるからだ.しかし、多くのAPIが操作を実行した後、
3.APIが要求を簡単に完了させる
あなたはいつもこのようにしたいのではないでしょうか.他の人に車でドライクリーニング店に連れて行かせたり、直接ドライクリーニング店に行かせたりして、車を降りてドアを開けてドライクリーニング店に入って、店員に服を持ってからドライクリーニング店を出てから車であなたのところに戻ります.だからあなたのAPIはクライアントに何度も呼び出さないでください.通常実行する必要があるサブタスクをするためだけです.この問題は、デフォルトのパラメータ値を指定し、クライアントが特定の要求に基づいてデフォルトのパラメータ値を上書きできるようにすることで解決できます.
私が今ずっと使っているAPIは私を苦しめ、時間もかかります.単純なリクエストだけで所定の製品を作成できるように設計されており、300~500 msの時間がかかりますが、往復7往復で300~500 msのリクエストを送信する必要があるように設計されています.これにより、300~500 msのプロセスに何秒もかかります.また、これらの増加した時間は、このAPIを使用して製品を予定している消費者に注目されます.
4.応答を適切に使用
この提案は前のいくつかの項目に基づいている.要求された操作処理が成功すると、
5.性能の問題を多く考慮する
優れたAPIは,いずれも大量のリクエストを迅速に処理できる.1つのリクエストを処理した後に得られた結果は、繰り返し処理する必要がなく、完全に同じリクエストに直接戻ることができます.すなわち、サーバ側キャッシュのような技術をできるだけ使用する必要があります.あるユーザがproduct 1の情報を要求し、数秒後にもう一人がproduct 1の情報を要求した場合、最初の要求に戻った結果を同じように後の要求に戻すことができます.再クエリーは必要ありません.さっき調べた同じデータを返すためだけです.キャッシュ内容が時代遅れにならないように、キャッシュに期限切れの時間を確保します.
Chargifyはこの方面でよくやった.私が彼らに予約した製品を要求したとき、彼らは200 ms前後で私の結果に返事することができます.これはかなり速いです.そして、もし私が1分後にこの予約製品を再び要求したら、97 ms以内に同じ結果を返してくれます.すべてのインタフェースやクエリーがそのように設計できるわけではないことも知っておく必要がありますが、データが変わらないか、頻繁に変わらない場合は、APIでキャッシュを使用してリクエストの処理を加速することを考慮します.あなたのクライアントはあなたを好きになります.クライアントが応答結果を独自のクライアントキャッシュにキャッシュすると、より満足できます.
6.SSL付きBasic Authで
Basic Auth(基本認証)、Digest Auth(要約認証)、OAuth(オープン認証)、no authなど、APIのセキュリティを保障する方法はたくさんあります.どの方法を使うかを考えるときに考慮しなければならないのは、認証方法の性能と使いやすさ(上記の提案5と提案3で述べたように).SSLを使用している場合は、Basic Authメソッドを使用することをお勧めします.導入が容易で、複数回ではなく1回だけ要求する必要があるため(Digest Authは通常、認証を完了するには少なくとも2回以上の要求が必要です)、パフォーマンスも相対的に高くなります.SSLを使用しない場合は、Digest AuthやOAuthなどの他の安全な認証方法をお勧めします.
7.APIのバージョンを作成する
おめでとう!あなたのAPIの設計は成功し、多くのユーザーに使用されています.今、彼らの多くの製品とプロジェクトはあなたのAPIに依存し始めました.しかし、彼らの使用に影響を与えずにAPIを更新する方法を考えなければなりません.異なるバージョンのAPIを互いに独立させることができる場合は、バージョン番号をパラメータまたはAPIネーミングの一部として使用することをお勧めします.例えば、
APIをバージョン番号で区切ることで、ユーザーは適切なときに新しいAPIに移行するまで、あるバージョンのAPIを使用することができます.既存のバージョンのAPIを処理する必要がなく、いつでもバージョンAPIをオフにすることもできます.
8.XMLではなくJSONを使用
第8条提案は私の個人的な好みに基づいて提出された.私は今まで多くのAPIを使ったことがあります.JSON形式もXML形式もあります.JSON形式の方が使いやすいと思います.JSONフォーマットは通常、より簡潔(伝送されるデータ量がより小さくなる)であり、複雑なオブジェクト(正確)を表現しやすく、他のフォーマットのように動作することができます(現在、誰もがJSONを使用しています).XMLは通常冗長であり、複雑な要素を容易に示すことができず、DTDを検証する必要があります.だから私はJSON形式を使います.XMLを使いたいなら勝手にしてください.いずれにしても、JSONを使い始めるとXMLの欠点が明らかになると思います.
まとめ
私が提案した8つの提案は、次に設計するAPIをよりよく考えることができます.APIは私たちと統合システムのインタラクション方式を変えているので、その品質は特に重要になります.APIを設計するときにターミナルユーザーを考慮すると、どのように使いやすくするかを考えなければなりません.そうすれば、APIがより成功します.ユーザーが別のAPIを使ってもあなたのAPIができることを完成することができますが、他の人のAPIは使いやすく、応答速度が速いので、ユーザーは自然に他の人のものを使ってあなたのものではありません.
だからこれらの深刻な間違いを犯してはいけません:パラメータのフォーマットが一致していないで、簡単な応答だけをして、さっき処理した結果に対して一言も言わないで(おしゃべりではありません)、しかも応答が遅いです.それはあなたのAPI全体を破壊します.もしあなたのAPIがあなたのビジネスであれば、それらの間違いはあなたのビジネス全体を黄色くします.ご拝読ありがとうございます.
私はすでに多くのAPI設計に関する文章と優秀なREST API設計チュートリアルを見たことがあります.彼らは通常、適切な符号化技術と、所与の言語でインタフェースを露出する方法について議論します.それらは役に立つことも必要ですが、APIをよりよく機能させる考えをよく無視しています.この記事では、APIサービス会社のプロジェクトで実践した8つのアドバイスを提供します.次のプロジェクトで使用できることを望んでいます.
1.適合性と統一性を勝ち取る
ここでは,APIを予測可能に設計することが要求される.このようにして、すべてのインタフェースとインタフェースに必要なパラメータを書きます.名前が一致し、インタフェースに必要なパラメータの順序も一致していることを確認します.あなたは今products、orders、customersのデータを持っているでしょう.idとnameを含むテーブルに存在するはずです.では、1つのインタフェースにIDのみを送信させないでください.もう1つのインタフェースにはnameのみを送信し、2つのインタフェースにも送信します.1つのインタフェースを
/product/IDに従って参照させないでください.もう1つのインタフェースを/ID/customerに従って参照させないでください.APIの利用者として同じ方法で2つの異なるリソースにアクセスしたいからです.もう1つのコンプライアンスを保証するテクニックは、パラメータ値のタイプを観察することです.一方のインタフェースのIDパラメータが整数型である場合、他方のインタフェースのIDパラメータを文字列型にしないでください.APIの使用者として、各インタフェースの各パラメータ値タイプを推測したくないからです.
インタフェースがどのようにデータにアクセスするかを考慮する必要があるほか、APIがどのようにデータを返し、データフォーマットの統一性を返すかをよく考えなければなりません.現在、私が最近使っているAPIでは大きな問題があります.開発でデータを返すインタフェースを使用すると、戻り結果(XML形式の...なぜ私がそれを避けるのかについて議論します)の各要素に特定の属性が含まれていることに驚きました.しかし、結果として、一部の要素にはその属性があり、他の要素はありません.私はむしろその属性が空の値であっても、その属性が全く見えないことを望んでいません.なぜなら、各要素を巡ってこのプロパティを探す場合は、値がなくても少なくとも見つけたいからです.しかし、データベースからいくつかのレコードを検出して、いくつかのデータの中にフィールドがなく、他のいくつかのレコードがあることを発見しました.そして、クエリーの結果を疑い、「消えた属性は私に失われたのか」という疑問を抱き始めました.
2.素直に考える
誰かに電話して何かしてもらったときに「はい!」と快く返事をした経験があるのではないでしょうか.通常、あなたはためらって「本当に手伝ってくれるの?」と聞きます.優れたAPIは、実行したい操作だけでなく、実行したばかりの操作に関する情報も追加で返されます.APIがproductの作成を担当している場合は、作成したばかりのproductに関する情報をクライアントに要求するのではなく、作成操作を実行した後に作成したばかりのproductに関する情報を返すようにします.それは君が頭が悪いように見えるからだ.しかし、多くのAPIが操作を実行した後、
200 OKのような情報だけを返すことに驚くでしょう.したがって、APIがクライアントに有用で明らかに必要な操作に関する情報を返すだけで、それを率直にすることができます.3.APIが要求を簡単に完了させる
あなたはいつもこのようにしたいのではないでしょうか.他の人に車でドライクリーニング店に連れて行かせたり、直接ドライクリーニング店に行かせたりして、車を降りてドアを開けてドライクリーニング店に入って、店員に服を持ってからドライクリーニング店を出てから車であなたのところに戻ります.だからあなたのAPIはクライアントに何度も呼び出さないでください.通常実行する必要があるサブタスクをするためだけです.この問題は、デフォルトのパラメータ値を指定し、クライアントが特定の要求に基づいてデフォルトのパラメータ値を上書きできるようにすることで解決できます.
私が今ずっと使っているAPIは私を苦しめ、時間もかかります.単純なリクエストだけで所定の製品を作成できるように設計されており、300~500 msの時間がかかりますが、往復7往復で300~500 msのリクエストを送信する必要があるように設計されています.これにより、300~500 msのプロセスに何秒もかかります.また、これらの増加した時間は、このAPIを使用して製品を予定している消費者に注目されます.
4.応答を適切に使用
この提案は前のいくつかの項目に基づいている.要求された操作処理が成功すると、
200 OKのようなステータスコードが返される.要求された動作処理が失敗した場合、処理が失敗したことを示すために、404または500のような適切なステータスコードが与えられる.なぜなら、クライアントがAPIを使用する際に、まず返されるステータスコードに基づいて、具体的な返されるコンテンツをどのように処理するかを決定することができるからである.私が今使っているAPIは確かに200 OKのステータスコードを返してくれますが、彼の直後の返信内容は処理に失敗したエラーメッセージです.そのため、リクエストが成功したことを知っていますが、リクエストの操作が本当に成功したかどうかを確認しなければなりません.だからこのように設計しないでください.最初から適切なステータスコードを返してから、どのように処理すればいいかを知るだけです.5.性能の問題を多く考慮する
優れたAPIは,いずれも大量のリクエストを迅速に処理できる.1つのリクエストを処理した後に得られた結果は、繰り返し処理する必要がなく、完全に同じリクエストに直接戻ることができます.すなわち、サーバ側キャッシュのような技術をできるだけ使用する必要があります.あるユーザがproduct 1の情報を要求し、数秒後にもう一人がproduct 1の情報を要求した場合、最初の要求に戻った結果を同じように後の要求に戻すことができます.再クエリーは必要ありません.さっき調べた同じデータを返すためだけです.キャッシュ内容が時代遅れにならないように、キャッシュに期限切れの時間を確保します.
Chargifyはこの方面でよくやった.私が彼らに予約した製品を要求したとき、彼らは200 ms前後で私の結果に返事することができます.これはかなり速いです.そして、もし私が1分後にこの予約製品を再び要求したら、97 ms以内に同じ結果を返してくれます.すべてのインタフェースやクエリーがそのように設計できるわけではないことも知っておく必要がありますが、データが変わらないか、頻繁に変わらない場合は、APIでキャッシュを使用してリクエストの処理を加速することを考慮します.あなたのクライアントはあなたを好きになります.クライアントが応答結果を独自のクライアントキャッシュにキャッシュすると、より満足できます.
6.SSL付きBasic Authで
Basic Auth(基本認証)、Digest Auth(要約認証)、OAuth(オープン認証)、no authなど、APIのセキュリティを保障する方法はたくさんあります.どの方法を使うかを考えるときに考慮しなければならないのは、認証方法の性能と使いやすさ(上記の提案5と提案3で述べたように).SSLを使用している場合は、Basic Authメソッドを使用することをお勧めします.導入が容易で、複数回ではなく1回だけ要求する必要があるため(Digest Authは通常、認証を完了するには少なくとも2回以上の要求が必要です)、パフォーマンスも相対的に高くなります.SSLを使用しない場合は、Digest AuthやOAuthなどの他の安全な認証方法をお勧めします.
7.APIのバージョンを作成する
おめでとう!あなたのAPIの設計は成功し、多くのユーザーに使用されています.今、彼らの多くの製品とプロジェクトはあなたのAPIに依存し始めました.しかし、彼らの使用に影響を与えずにAPIを更新する方法を考えなければなりません.異なるバージョンのAPIを互いに独立させることができる場合は、バージョン番号をパラメータまたはAPIネーミングの一部として使用することをお勧めします.例えば、
GET /v1/product/idまたはGET /v2/product/idまたはGET /product/id?v=1.バージョン番号をHTTPリクエストヘッダに配置することもできますが、どの方法を採用してもすべてのバージョンが同じ方法を採用していることを確認する必要があります.APIをバージョン番号で区切ることで、ユーザーは適切なときに新しいAPIに移行するまで、あるバージョンのAPIを使用することができます.既存のバージョンのAPIを処理する必要がなく、いつでもバージョンAPIをオフにすることもできます.
8.XMLではなくJSONを使用
第8条提案は私の個人的な好みに基づいて提出された.私は今まで多くのAPIを使ったことがあります.JSON形式もXML形式もあります.JSON形式の方が使いやすいと思います.JSONフォーマットは通常、より簡潔(伝送されるデータ量がより小さくなる)であり、複雑なオブジェクト(正確)を表現しやすく、他のフォーマットのように動作することができます(現在、誰もがJSONを使用しています).XMLは通常冗長であり、複雑な要素を容易に示すことができず、DTDを検証する必要があります.だから私はJSON形式を使います.XMLを使いたいなら勝手にしてください.いずれにしても、JSONを使い始めるとXMLの欠点が明らかになると思います.
まとめ
私が提案した8つの提案は、次に設計するAPIをよりよく考えることができます.APIは私たちと統合システムのインタラクション方式を変えているので、その品質は特に重要になります.APIを設計するときにターミナルユーザーを考慮すると、どのように使いやすくするかを考えなければなりません.そうすれば、APIがより成功します.ユーザーが別のAPIを使ってもあなたのAPIができることを完成することができますが、他の人のAPIは使いやすく、応答速度が速いので、ユーザーは自然に他の人のものを使ってあなたのものではありません.
だからこれらの深刻な間違いを犯してはいけません:パラメータのフォーマットが一致していないで、簡単な応答だけをして、さっき処理した結果に対して一言も言わないで(おしゃべりではありません)、しかも応答が遅いです.それはあなたのAPI全体を破壊します.もしあなたのAPIがあなたのビジネスであれば、それらの間違いはあなたのビジネス全体を黄色くします.ご拝読ありがとうございます.