Web APIの開発は、URL、HTTPステータスコード、ヘッダー、リクエストコンテンツだけではありません。 設計プロセス（APIの外観と認識方法）は非常に重要であり、ビジネスの成功への優れた投資です。 この記事では、特にWebおよびHTTPプロトコルの利点に基づいてAPIを設計する方法について簡単に説明します。 しかし、これがHTTPにのみ適用されるとは思わないでください。 何らかの理由でWebSockets、XMPP、MQTTなどを使用してサービスの作業を実装する必要がある場合-すべての推奨事項のほとんどを使用して、ほぼ同じAPIが機能します。 さらに、作成されたAPIにより、いくつかのプロトコル上での作業の開発と保守が容易になります。

良いデザインは、URL、ステータスコード、ヘッダー、リクエストコンテンツに影響します

通常、Web API設計ガイドは一般的な概念に焦点を当てています：URLの設計方法、HTTPステータスコードの正しい使用方法、ヘッダーで伝達するもの、シリアル化されたデータまたはオブジェクトグラフで表されるコンテンツ設計の設計方法。 これらはすべて非常に重要な実装の詳細ですが、一般的なAPI設計という点ではそれほど重要ではありません。 APIの設計は、サービスの本質をどのように説明し提示するかであり、Web APIの成功と使いやすさに大きく貢献します。



優れた設計プロセスまたは方法論は、Web APIとして利用可能なサービスコンポーネントを作成するための一貫した再現可能な手順のセットを提供します。 つまり、開発者、設計者、およびアーキテクトは、このような透過的な方法論を使用して、ソフトウェア実装に関するアクションを調整できます。 方法論の詳細を損なうことなくプロセスが改善および自動化されるので、使用される方法論は時間とともに改良することもできます。 実際、2つのアクティビティが完全に分離して文書化されている場合、 設計プロセスに関係なく、 実装の詳細 （プラットフォーム、OS、フレームワーク、UIスタイルなど）が変更される場合があります。

7つのステップでAPIを設計します。

以下は、RichardsonとAmundsenによるRESTful Web APIで説明されている方法論の簡単な概要です。 この記事は、各ステップの詳細な分析を意味するものではありませんが、各ステップで何が行われるのかを一般的に理解しようとします。 また、読者は、このレビューを、知識とビジネス目標の詳細を考慮したWeb API設計プロセスを設計するためのガイドとして使用できます。



注意事項：はい、7ステップのマニュアルはかなり大きく見えるかもしれませんが、実際には、サービスの実装と公開に関する追加として5つの設計ステップと2つしかありません。 これらの2つのアドオンはプロセスを中心に構築され、最初から最後までプロセス全体を記述します。



計画では、サービスを作成するプロセスの反復的な性質を考慮する必要があります。 たとえば、ステップ2（状態図の作成）を実行すると、ステップ1（すべてのコンポーネントのリスト）でまだやるべきことがあることがわかります。 コードを書くとき（ステップ6）、ステップ5（セマンティックプロファイルの作成）などでいくつかの点を見逃したことがあります。 重要なポイントは、マニュアルを使用してできるだけ多くの詳細を見つけ、不足しているポイントを説明するために1つまたは2つ前に戻ることです。 反復性は、サービスの最も完全な表現を構築し、それがクライアントアプリケーションでどのように使用されるかを確認するための鍵です。

ステップ1：すべてのコンポーネントをリストする

最初のステップは、クライアントアプリケーションがサービスを使用して送受信する可能性があるすべてのタイプのデータをリストすることです。 これを意味記述と呼びます。 セマンティック -アプリケーション内のデータの意味と説明を表示するため-アプリケーション自体で何が起こっているかの説明を含むため。 サービスではなく、クライアントアプリケーションの観点から作業する必要があることに注意してください 。 クライアントが使用する使いやすいAPIを開発することが重要です。



たとえば、リストタイプの簡単なアプリケーションでは、次のセマンティックの説明を見つけることができます。

• id-システム内の各エントリの一意の識別子
• title-各「ケース」の名前
• dateDue-「ケース」が完了するべき日付
• complete-「ケース」が完了したかどうかを示す「yes / no」フラグ

このアプリケーションでは、「業務」のカテゴリ（仕事、家族、庭など）、ユーザー情報などの概念を表示するための多くのポイントがあります。 ここで、プロセス自体に集中できるように、このような単純なリストを検討する方が良いでしょう。

ステップ2：状態図を描く

次のステップは、目的のAPIの状態図を作成することです。 図の各ブロックは、可能な状態、つまり最初のステップで見つかった1つ以上のセマンティック記述子を含むドキュメントを表します。 矢印を使用して、ある状態から次の状態への遷移を示すことができます。 これらの遷移はクエリによってトリガーされます。



これまでのところ、各遷移に使用する方法を決定することについて心配する必要はありません。 移行が安全か（HTTP GET）、安全でない/べき等（HTTP POST）、または安全でない/べき等（PUT）かを示すだけです



限界ノート：べき等アクションとは、予期しない副作用なしに繰り返すことができるアクションです。 たとえば、HTTP PUT は、サーバーがクライアントから受信した状態値を使用してターゲットリソースの値を置き換える必要があると仕様が規定しているため、べき等です。 HTTP仕様で は、POST を 介して渡された値は 既存のリソースに追加されるべきであり、置き換えられるべきで は ない ことを示して いるため、HTTP POSTは i等で はあり ません 。



この場合、最も単純な「To Doリスト」のクライアントアプリケーションには、リストアイテムへのアクセス、フィルタリング、個々のアイテムの表示、および完了としてマークする機能が必要になる場合があります。 これらのアクションの多くは、状態値を使用して、クライアントとサーバー間でデータを転送します。 たとえば、「アイテムの追加」アクションを使用すると、クライアントはtitleおよびdueDateのステータス値を渡すことができます。 以下は、主なアクションを示す図です。







図に示され、以下にリストされているアクションもセマンティック記述子です-それらはサービスのアクションのセマンティクスを記述します。

• 読み取りリスト
• フィルターリスト
• 読み取り項目
• 作成アイテム
• マーク完了

チャートでの作業中に、クライアントが必要とするいくつかのアクションやデータを見逃していることがあります。 この場合、これは1つのステップに戻って不足しているデータを入力し、ステップ2の図を改善する絶好の機会です。



これらの2つの手順を数回実行すると、クライアントがサービスと対話するために必要なすべてのデータとアクションを十分に理解できるようになります。

ステップ3：マジックストリングの一致

次のステップは、サービスのインターフェースですべての「魔法の線」を調整することです。 この場合、「マジックライン」はすべて記述子名になります。タスクの範囲外では意味がなく、単にサービスと通信するときにクライアントが参照するアクションまたはデータ要素を表します。 名前の一致とは、たとえば次のリソースを使用して、一般的に使用される用語に名前を付けることを意味します。

• schema.org
• microformats.org
• ダブリンコア
• IANAリンク関係値

これらはすべて、定式化され、広く使用されている名前のリポジトリです。 これらのサービスの名前を使用するときは、開発者があなたと同じ方法でそれらを理解するようにしてください。 このようなプロセスにより、APIの使いやすさが大幅に向上します。



注意事項：記述子に共通名を使用することは、フロントエンドにとっては良い考えかもしれませんが、内部のニーズのためにそれらを使用することを強制する人はいません。 これは、たとえば、データベース名を指します。 サービスは、外部名と内部名の対応マップを問題なく独立して使用できます。



この例のTo-Doサービスでは、1つの「create-item」を除くすべての記述子の受け入れ可能な既存の名前を見つけることができました。 この場合、 Web-Linking RFC 5988からルールベースの一意のURIを作成することにしました。 インターフェイスの従来の名前を選択すると、常に危険にさらされます。 内部名に完全に一致するものを見つけることができるのはまれであり、これは正常です。



ここに私が得たものがあります：

• id-> Dublin Coreからの識別子
• title- > Schema.orgからの名前
• dueDate-> Schema.orgのscheduledTime
• 完了-> Schema.orgからのステータス
• read- list- > IANA Link Relation Valuesからのコレクション
• filter- list- > IANAリンク関係値から検索
• read- item- > IANA Link Relation Valuesのアイテム
• create-item-> RFC5988を使用したhttp://mamund.com/rels/create-item
• マーク完了-> IANAリンク関係値から編集

そのため、名前の一致を使用した後のグラフの外観は次のとおりです。

ステップ4：ハイパーメディアタイプの選択

APIの設計プロセスの次のステップは、サーバーとクライアント間でメッセージを転送するために使用されるデータのタイプを選択することです。 ネットワークの特徴の1つは、データが共通のインターフェイスを介して標準化されたドキュメントによって送信されることです。 同じデータ記述子（「識別子」、「ステータス」）およびアクション（「検索」、「編集」）をサポートするタイプを選択することは非常に重要です。 そのような形式はほとんどありません。



リストの最上部からのハイパーメディア形式の一部を次に示します（このリストでは順序は関係ありません）。

• ハイパーテキストマークアップ言語（ HTML ）
• ハイパーテキストアプリケーション言語（ HAL ）
• コレクション+ JSON（ Cj ）
• サイレン
• JSON API
• 表現を交換するための統一基盤（ UBER ）

また、選択は、選択したハイパーメディア形式がデータ転送プロトコルでどれだけうまく機能するかによっても影響を受けるはずです。 ほとんどの開発者は、サービスインターフェイスにHTTPプロトコルを好みます。 ただし、 WebSockets 、 XMPP 、 MQTT 、およびCoAPも使用されます。特に、ショートメッセージ、ポイントツーポイント接続を使用した高速実装の場合に使用されます。



この例では、メッセージプロトコルとしてHTMLを使用し、通信プロトコルとしてHTTPを使用します。 HTMLはすでに必要な記述子（リストの場合は<UL>、要素の場合は<LI>、データの場合は<SPAN>）をサポートしています。 また、アクション記述子を適切にサポートしています（安全なリンクの場合は<A>、安全な移行の場合は<FORM method = "get">、安全でない移行の場合は<FORM method = "post">）。



注釈：状態図に「編集」がべき等（HTTP PUT）として表示されるようになりましたが、HTMLにはまだPUTの組み込みサポートがありません 。 ただし、べき等のHTML POSTをエミュレートするための追加フィールドを追加できます 。



これで、ダイアグラムの状態に基づいてインターフェイスを「テスト」できます。 この例では、「To-Doリスト」と「To-Doアイテム」の2つだけを説明する必要があります。

HTML ビューの コレクション「 To Do リスト 」

<html> <head> <!-- for test display only --> <title>To Do List</title> <style> .name, .scheduledTime, .status, .item {display:block} </style> </head> <body> <!-- for test display only --> <h1>To-Do List</h1> <!-- to-do list collection --> <ul> <li> <a href="/list/1" rel="item" class="item"> <span class="identifier">1</span> </a> <span class="name">First item in the list</span> <span class="scheduledTime">2014-12-01</span> <span class="status">pending</span> </li> <li> <a href="/list/2" rel="item" class="item"> <span class="identifier">2</span> </a> <span class="name">Second item in the list</span> <span class="scheduledTime">2014-12-01</span> <span class="status">pending</span> </li> <li> <a href="/list/3" rel="item" class="item"> <span class="identifier">3</span> </a> <span class="name">Third item in the list</span> <span class="scheduledTime">2014-12-01</span> <span class="status">complete</span> </li> </ul> <!-- search transition --> <form method="get" action="/list/" class="search"> <legend>Search</legend> <input name="name" class="identifier" /> <input type="submit" value="Name Search" /> </form> <!-- create-item transition --> <form method="post" action="/list/" class="> <legend>Create Item</legend> <input name="name" class="name" /> <input name="scheduledTime" class="scheduledTime" /> <input type="submit" value="Create Item" /> </form> </body> </html>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

HTML ビューの コレクション「To Doアイテム」

 <html> <head> <!-- for test display only --> <title>To Do List</title> <style> .name, .scheduledTime, .status, .item, .collection {display:block} </style> </head> <body> <!-- for test display only --> <h1>To-Do Item</h1> <a href="/list/" rel="collection" class="collection">Back to List</a> <!-- to-do list collection --> <ul> <li> <a href="/list/1" rel="item" class="item"> <span class="identifier">1</span> </a> <span class="name">First item in the list</span> <span class="scheduledTime">2014-12-01</span> <span class="status">pending</span> </li> </ul> <!-- edit transition --> <form method="post" action="/list/1" class="edit"> <legend>Update Status</legend> <input type="hidden" name="etag" value="q1w2e3r4t5y6" class="etag" /> <input type="text" name="status" value="pending" class="status" /> <input type="submit" value="Update" /> </form> </body> </html>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

状態図のおおよその実装を使用する場合、何かが足りないことに気付く場合があり、1つまたは2つ前に戻る必要があることに注意してください。 これは正常であり、怖がらないでください。 今こそ、すべてをコードで実装する前に、テストケースですべてを試すときです。



すべての表示方法に満足したら、コーディングを開始する前の最後のステップは、 セマンティックプロファイルを作成することです 。

ステップ5：セマンティックプロファイルの作成

セマンティックプロファイルは、ソリューション内のすべての記述子をリストし、各記述子の詳細を説明するドキュメントであり、開発者がクライアントとサーバーの両方の実装を作成するのに役立ちます。



これは実装ガイドであり、実装の指示ではないことを明確に理解する必要があります。

サービス記述形式

サービスを記述するためのフォーマットは長い間存在しており、コードを生成したり、サービスの既存の実装を文書化したいときに非常に便利です。



開発者の心のために戦う主な形式：

• Webサービス定義言語（ WSDL ）
• Atomサービスの説明（ AtomSvc ）
• Webアプリケーション記述言語（ WADL ）
• 設計図
• Swagger
• RESTfulアプリケーションモデリング言語（ RAML ）

プロファイル記述形式

現在のところ、プロファイルの説明にはいくつかの形式しかありません。 そして、私がお勧めするものは次のとおりです。

• アプリケーションレベルのセマンティックプロファイル（ ALPS ）
• JSON-LD + Hydra

どちらの形式もかなり新しいものです。 JSON-LD仕様は、2014年の初めにW3C勧告のステータスを取得しました。Hydraは（執筆時点では）非公式のドラフト状態のままですが、活発な開発者コミュニティがあります。 ALPSはドラフトの初期段階にもあります。



このドキュメントのアイデアは問題領域の実際の側面を記述することであり（特定のソリューションではない）、形式は典型的な記述形式とは非常に異なります。

 <html> <alps version="1.0"> <doc> ALPS profile for InfoQ article on "API Design Methodology" </doc> <!-- data descriptors --> <descriptor id="identifier" type="semantic" ref=" /> <descriptor id="name" type="semantic" ref=" /> <descriptor id="scheduledTime" type="semantic" ref=" /> <descriptor id="status" type="semantic" ref=" /> <!-- action descriptors --> <descriptor id="collection" type="safe" ref=" /> <descriptor id="item" type="safe" ref="> <descriptor href="#identifier" /> </descriptor> <descriptor id="search" type="safe" ref="> <descriptor href="#name" /> </descriptor> <descriptor id="create-item" type="unsafe" ref="> <descriptor href="#name" /> <descriptor href="scheduledTime" /> </descriptor> <descriptor id="edit" type="idempotent" ref="> <descriptor href="#identifier" /> <descriptor href="#status" /> </descriptor> </alps>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ドキュメントは、to-doリストサービスインターフェイスからのフィールドとアクションのすべての可能な値の一般的な辞書のように見えることに気づいたでしょう。これがアイデアの本質です。 このプロファイルに従うことに同意するサービスは、プロトコル、メッセージ形式、さらにはURLについても独自の決定を下すことができます。 このプロファイルを受け入れることに同意するクライアントは、記述子を理解し、可能であればアクティブ化するような方法で作成されます。



これは次の場合にも最適な形式です。

• 人が読める形式でドキュメントを生成し、
• 同様の形式の分析
• 最も一般的に使用されるプロファイルの追跡、
• 状態図を生成することもできます。

しかし、これは別の記事のトピックです。



一貫性のある名前、状態図の簡単なメモ、およびセマンティックプロファイルを持つ記述子の完全なリストができたので、サービスとクライアントのコードを書き始める準備ができました。

ステップ6：コードを書く

この瞬間から、ベストプラクティス（状態図とセマンティックプロファイル）をサーバー側とクライアント側の開発者に転送して、特定の実装を実行できます。



HTTPサーバーは2番目のステップからダイアグラムを実装する必要があり、クライアントからの要求はサービス状態間の遷移をトリガーする必要があります。 サービスから送信される各ビューは、手順3で選択した形式で、手順4で作成したプロファイルへのリンクを含める必要があります。応答には、状態図からアクションを実装する適切なハイパーメディアコントロールを含める必要があり、ドキュメントプロファイルで説明します。 クライアント部分とサーバー部分の開発者は、これからは比較的独立したコードを書くことができますが、状態図とプロファイルに準拠するためのテストを実行することを忘れないでください。



コードを記述して安定化した後、リストの最後のステップである「公開」が残ります。

ステップ7：APIを公開する

Web APIは、顧客の要求に常に応答するURLを少なくとも1つ公開する必要があります-遠く離れた将来であってもです。 私はそれを「ビルボードURL」と呼んでいます。誰もが知っています。 また、プロファイルドキュメントを発行して、新しいサービスの実装が応答でそれを参照できるようにすることをお勧めします。 また、このアドレスで、開発者がサービスを理解して使用するのに役立つ読みやすいドキュメント、レッスン、およびその他の情報を公開することもできます。



最終的には、適切に設計された、安定した、手頃な価格の、実用的なサービスを利用できるはずです。

結論として

この記事では、Web用のAPIを構築するための一連のステップの概要を説明します。 主な焦点は、正しいデータ記述子とアクションを取得することです。 直接通信しなくても、クライアントとサーバーのパーツを簡単に記述できるように、機械読み取り用に文書化します。



もう一度7つのステップ：

1. すべての部品をリストする
   
   クライアントがサービスと通信するために必要なすべてのタイプのデータを示します。
2. 状態図を描く
   
   サービスで利用可能なすべてのアクション（状態遷移）を文書化する
3. マジック変数に一致
   
   パブリックインターフェイスの名前を受け入れられた標準にする
4. ハイパーメディアの種類を選択してください
   
   選択したプロトコルを考慮して、サービスの遷移を最も完全に表示するメッセージ形式を選択します。
5. セマンティックプロファイルの作成
   
   サービスで使用されるすべての記述子を含み、定義するドキュメントを作成します
6. 実装を書く
   
   推奨事項に従ってコードを記述し、必要に応じてプロファイル/図を編集できるように、サーバーおよびクライアント部分の開発者間でセマンティックプロファイルと状態図を配布します。
7. APIを公開する
   
   ビルボードURLとセマンティックプロファイルを公開して、他の人がそれらを使用して新しいサービスやクライアントアプリケーションを作成できるようにします。

ほとんどの場合、いくつかのステップに戻って再度実行し、欠落データを作成するか、設計プロセスで見つかった妥協点を表示する必要があります。 これが早ければ早いほど良い。 将来のある時点でこれらの開発をAPIで使用して、開発者が必要とする新しい形式とプロトコルで新しい実装を作成することもできます。



結局のところ、この方法論は、信頼性、再現性、一貫性、およびシームレスなWeb API設計プロセスを作成するための1つの方法にすぎません。 この例を検討する過程で、場合によってはいくつかのステップを追加する必要があり、いくつかを短縮する必要があることを決定できます。もちろん、データ交換形式とプロトコルの選択に関する決定は、プロジェクトによって大きく異なる場合があります。



この記事が、組織またはチームでAPIを作成するための最適な方法論を構築する方法を検討するための参考になることを願っています。

---

この記事は、Layer 7 Technologiesの リードAPIアーキテクトであるMike Amundsenによって書かれました 。 彼はまた、本の著者および講演者、米国およびヨーロッパ中の旅行コンサルタントとしても知られています。



記事のトピックがあなたに近い場合、またはAPIを適切に設計、保守、操作する方法について詳しく知りたい場合は、 API＆バックエンド会議に参加してください！

あなたが何か伝えることがあれば、 私たちはあなたの物語を待っています ！