REST APIの設計と生成：Visual Paradigmを活用した包括的なガイド - Go TOGAF Japanese

はじめに

現代のソフトウェア開発の世界において、アプリケーションプログラミングインターフェース（API）は、異なるシステムやサービス間のデジタル通信の基盤となっています。APIの設計に用いられるさまざまなアーキテクチャスタイルの中でも、REST（Representational State Transfer）は、そのシンプルさ、スケーラビリティ、ステートレスな性質から、主流のアプローチとして浮上しています。REST APIは、標準的なHTTPプロトコルを使用してインターネット上で異なるソフトウェアアプリケーションが通信できるようにし、プラットフォームに依存せず広く利用可能となっています。

しかし、REST APIの設計、文書化、実装は、一貫性や適切な文書化、およびサービス提供者と利用者の両方にとって使いやすさを確保する場合、複雑で時間がかかるプロセスとなることがあります。このような課題を解決するのがVisual Paradigmです。これは、設計からデプロイまでを含むREST APIのライフサイクル全体をスムーズにする強力なモデリングツールです。

Model-Drivven REST API Development

この包括的な事例研究では、Visual ParadigmがREST API開発プロセス全体をどのように支援するかを検証します。UMLクラス図を用いた初期設計から、本番環境対応のコード生成、包括的なAPI文書化までをカバーします。また、提供者視点（APIの設計と実装）と利用者視点（APIへのアクセスと利用）の両方を歩みながら、各ステップにおける実用的な洞察を提供します。

REST APIの基本を理解する

REST APIとは何か？

RESTという言葉は、REpresentational State Transferを意味します。これはネットワークアプリケーションを設計する際に用いられるアーキテクチャスタイルです。RESTアーキテクチャの制約に従うWebサービスAPIは、RESTful、またはREST APIと呼ばれます。

REST APIは、Uniform Resource Identifiers（URI）によって識別されるリソースを対象に動作します。これらのリソースは、GET、POST、PUT、PATCH、DELETEなどの標準的なHTTPメソッドを使って操作されます。RESTの主な原則は以下の通りです：

ステートレス性：クライアントからの各リクエストには、処理に必要なすべての情報が含まれている
クライアント・サーバー分離：クライアントとサーバーは独立して動作する
キャッシュ可能性：応答は、キャッシュ可能かどうかを明示的に示さなければならない
一貫したインターフェース：リソースを操作するための標準的なメソッド

Visual ParadigmがREST APIをどのようにサポートするか

Visual Paradigmは、REST APIの基盤となる通信モデルのモデリング、REST APIおよびAPI文書の生成をサポートしています。このプラットフォームは、RESTfulサービスの設計に視覚的なアプローチを提供し、APIの概念化、文書化、実装をより容易にします。

以下のアクティビティ図は、提供者がREST APIおよび関連するAPI文書を作成するために取るステップを示しています：

Activity Diagram - How can a provider design and produce the REST API?

アクティビティ図 – 提供者はREST APIをどのように設計・生成するか？

まず、サービス提供者は、RESTサービス、リクエストボディ、レスポンスボディを可視化するクラス図を使って、通信モデルを設計します。その後、クラス図からREST APIとAPI文書を生成できます。次に、提供者はサービスロジックのプログラミングを進めます。完了後、サービスをデプロイし、自社のウェブサイトにAPIを公開できます。

以下のアクティビティ図は、利用者がサービスを使用するために取るステップを示しています：

Activity Diagram - How can a client access a service with REST API?

アクティビティ図 – クライアントはREST APIを使ってサービスにどのようにアクセスするか？

サービスの利用者は、API文書ページにアクセスし、XMLファイルをダウンロードしてから、Visual Paradigmにインポートします。これにより、サービスにアクセスするために必要なソースコードとAPIを生成できます。最終ステップとして、生成されたソースコードを使って、サービスを利用するアプリケーションをプログラミングします。

第1部：UMLを用いたREST APIの設計

UMLを用いたREST APIの設計方法は？

リソース、リクエストボディ、レスポンスボディを表すクラス図を描くことで、REST APIを設計できます。

RESTリソースの作成

RESTリソースは、RESTに準拠するウェブサービスの基本単位です。URI、HTTPリクエストメソッド、関連するパラメータ、リクエスト/レスポンスボディを持つオブジェクトです。各RESTリソースは、そのURIプロパティで指定されたパスに存在する特定のサービスを表しています。したがって、複数のサービスをモデル化したい場合は、複数のRESTリソースを描画してください。

RESTリソースの作成手順ガイド

ステップ1：新しいクラス図の作成

選択してください 図 > 新規作成アプリケーションツールバーから。 新しい図 ウィンドウで、 クラス図 を選択し、次に次へ。図の名前と説明を入力し、次に OK.

ステップ2：RESTリソースツールの選択

選択してください RESTリソース を図のツールバーから選択してください。

Select REST Resource in diagram toolbar

図のツールバーからRESTリソースを選択

ステップ3：RESTリソースの作成

図上でクリックしてRESTリソースを作成します。短く意味のある名前を付けてリソースの名前を指定してください。

REST Resource created

RESTリソースが作成されました

ステップ4：リソース仕様の開く

RESTリソースを右クリックし、 仕様を開く… をポップアップメニューから選択します。

Opening the specification of REST Resource

RESTリソースの仕様を開く

ステップ5：一般プロパティの入力

で一般タブで、以下の項目を入力してください：

プロパティ	説明
URI	各RESTリソースには独自のURIがあります。コンシューマーはURLにアクセスすることでRESTリソースにアクセスします。通常、RESTfulなURIは行動を指すのではなく、物（もの）を指すようにするべきです。したがって、URIを決定する際は、動詞ではなく名詞を使用するように心がけてください。
メソッド	リソースに対して実行するアクションを指定します。詳細については、以下のセクションを参照してください。メソッド（HTTPメソッド）以下。
説明	生成されたAPIドキュメントに表示されるリソースの説明です。サービスの内容と利用方法がコンシューマーに理解しやすいように、明確な説明を提供することをお勧めします。

RESTリソースの一般プロパティ

URI, method and description filled

URI、メソッド、説明が入力済み

ステップ6：リクエストボディのモデル化（POST、PUT、PATCH、DELETE用）

RESTリソースがPOST、PUT、PATCH、またはDELETEメソッドを使用し、リソースを使用する際にパラメータが必要な場合、クラスを描画してパラメータをモデル化します。 RESTリクエストボディ アイコンにマウスカーソルを移動します。 リソースカタログ ボタンを押してドラッグしてください。

Create class from REST Request Body

RESTリクエストボディからクラスを作成する

マウスボタンを離して、 関連 -> 1つのクラス をリソースカタログから選択します。

Select One Class

1つのクラスを選択

マウスボタンを離してリクエストクラスを作成します。デフォルトでは、RESTリソースに基づいてクラス名が付けられます。必要に応じて名前を変更できます。たとえば、/members RESTリソースを使ってメンバーを作成する場合、メンバーの詳細情報をサーバーに送信してメンバー記録を作成する必要があります。そのため、クラス名を Member として、メンバーの詳細情報を格納するクラス名にします。

Class created from REST Request Body

RESTリクエストボディから作成されたクラス

クラスに属性を追加します。これらの属性は、サーバーに送信するデータを保持します。

Attributes added

属性が追加されました

クラスモデルとJSON形式のリクエストボディの表現との比較です。

Comparison between class model and Request Body in JSON

クラスモデルとJSON形式のリクエストボディとの比較

ステップ7：モデルレスポンスボディ

次に、RESTリソースのレスポンス部分の設計に進んでください。 RESTレスポンスボディ アイコンにマウスを合わせてください。サービスが単純なデータ値またはオブジェクトを返す場合、 リソースカタログ ボタンを押してドラッグしてください。次に、 関連 -> 1つのクラス リソースカタログから選択してください。サービスがオブジェクトの配列を返す場合、 関連 -> 複数のクラス リソースカタログから選択してください。

Create class from REST Response Body

RESTレスポンスボディからクラスを作成する

クラスに名前を付け、属性をクラスに追加してください。

Class created from REST Response Body

RESTレスポンスボディから作成されたクラス

クラスモデルとJSON形式のレスポンスボディの表現との比較です。

Comparison between class model and Response Body in JSON

クラスモデルとJSON形式のレスポンスボディとの比較

GETを使用するRESTリソースのパラメータの指定

パラメータとは、サービスにデータを渡すために使用されるクエリパラメータを指します。たとえば、「通貨変換」サービスを使用する場合、変換する金額、現在の通貨、および対象通貨をサービスに渡す必要があるでしょう。その結果、変換された金額を受け取ることができます。したがって、変換する金額、現在の通貨、および対象通貨がサービスのパラメータとなります。

パラメータの特徴の一つは、オプションであるということです。もう一つの特徴は、重複が許容されるということです。つまり、同じパラメータを複数回追加できます。

HTTPリクエストを送信する際、パラメータはURLのパスに追加されます。パラメータ付きのURLは次のようになります： http://www.example.com?age-limit=18

RESTリソースにパラメータを追加するには：

RESTリソースを右クリックして、 新しいパラメータ ポップアップメニューから選択してください。

New parameter

新しいパラメータ

パラメータの名前を入力してください。必要に応じて、タイプも指定できます。タイプの指定は文書化の目的のみです。コンシューマーが期待されるデータの種類を理解するのに役立ちますが、コードレベルでは何の影響もありません。コードでは、パラメータは常にキーと値の両方が文字列であるマップに格納されます。

Parameter created

パラメータが作成されました

押してください Enter.
すべてのパラメータを作成するには、ステップ2と3を繰り返してください。完了したら Esc すべてのパラメータの作成が完了したら

Parameters created

パラメータの作成完了

複数のシナリオのモデル化

場合によっては、複数または異なるレスポンスボディを含む複数のシナリオをモデル化する必要があることがあります。たとえば、返される可能性のあるさまざまなHTTPステータスコードを定義したい場合や、一部のケースではメインのレスポンスオブジェクト内に埋め込まれたエラー对象を返す必要がある場合があります。

例：

ケース1：

レスポンスヘッダー：status : 200 OK
レスポンスボディ：{“customer” : {“name” : “Peter”}}

ケース2：

レスポンスヘッダー：status : 400 Bad Request
レスポンスボディ：{“customer”: {“error” : {“text” : “無効な顧客名です。”}}}

これを表現するには、RESTリソースから複数のレスポンスボディをドラッグするだけです。2番目のレスポンスボディをドラッグする際にはステータスコードがプロンプトされます。また、RESTリソースとレスポンスボディを接続する関連付けを右クリックし、ポップアップメニューから ステータスコード… をポップアップメニューから選択します。

Creating the second Response Body

2番目のレスポンスボディの作成

パート2：ヘッダーと例の指定

リクエストヘッダーとリクエスト例の指定

HTTPメッセージは、HTTPリクエストライン、ヘッダー項目のコレクション、およびオプションのボディから構成されます。コンシューマーがRESTリソースにアクセスできるようにするには、リクエストヘッダーとリクエスト（ボディ）例を指定する必要があります。これにより、リクエストヘッダーと例が生成されたAPIドキュメントに表示されます。コンシューマーは、サービスの使用に関して仕様に従うことができます。

RESTリソースを右クリックし、 仕様を開く… をポップアップメニューから選択します。
を開きます。リクエストボディ タブ。
に入力します。ヘッダーREST APIの概要ページで述べたように、RESTは標準ではなくアーキテクチャスタイルです。RESTはHTTP標準を利用しているため、任意のREST呼び出しヘッダーは実際にはHTTPヘッダーです。
入力してください例 JSON形式で。

Request header and example specified

リクエストヘッダーと例が指定されました

レスポンスヘッダーとレスポンス例の指定

同様に、レスポンスヘッダーおよびレスポンス（本文）の例を指定する必要があります。これにより、生成されたAPIドキュメントにレスポンスヘッダーと例が表示されます。

RESTリソースを右クリックし、を選択してください仕様を開く… ポップアップメニューから。
を開いてくださいレスポンス本文 タブ。
入力してください ヘッダー.
入力してください例 JSON形式で。

Response header and example specified

レスポンスヘッダーと例が指定されました

ヘッダー（HTTPヘッダー）

HTTPヘッダーは、任意のHTTPリクエストおよびレスポンスの核心となるコンポーネントであり、HTTPトランザクションの動作パラメータを定義します。WebブラウザでURLにアクセスすると、WebブラウザはHTTPリクエストを送信し、その内容は次のようになります：

GET / HTTP/1.1
Host: www.visual-paradigm.com
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:33.0) Gecko/20100101 Firefox/33.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Cookie: landing=b7b93a316f374b13af4d5904c9797dcc; __utma=...
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

以前述べたように、RESTは標準ではなくアーキテクチャスタイルです。RESTはHTTP標準を利用しています。したがって、任意のREST呼び出しヘッダーは実際にはHTTPヘッダーです。

メソッド（HTTPメソッド）

HTTPメソッド、または時としてHTTP動詞と呼ばれるもので、リソースに対して実行するアクションを指定します。最もよく使われるHTTPメソッドは、GET、PUT、POST、DELETEであり、それぞれ読み取り、更新、作成、削除操作に対応しています。

メソッド	説明
GET	GETメソッド（またはGETリクエスト）は、リソースの表現を取得するために使用されます。データの取得にのみ使用し、状態を変更してはいけません。
PUT	PUTメソッド（またはPUTリクエスト）は、リソースを更新するために使用されます。たとえば、ブログ記事が http://www.example.com/blogs/123 に存在することを知っている場合、その特定の記事を更新するために、PUTメソッドを使用して記事の新しいリソース表現を置き換えることができます。
POST	POSTメソッド（またはPOSTリクエスト）は、リソースを作成するために使用されます。たとえば、新しいブログ記事を追加したいが、どこに保存すべきか分からない場合、POSTメソッドを使用してURLに投稿し、サーバーにURLを決定させることができます。
PATCH	PATCHメソッド（またはPATCHリクエスト）は、リソースを変更するために使用されます。完全なリソースではなく、リソースに対する変更内容を含みます。
DELETE	DELETEメソッド（またはDELETEリクエスト）は、URIで識別されるリソースを削除するために使用されます。

さまざまなHTTPメソッドの説明

パート3：UMLからREST APIを生成する

RESTリソースのモデリングが完了したら、APIを生成し、必要に応じてAPIドキュメントも生成できます。

REST APIの生成（プロバイダー視点）

REST APIを生成するには：

選択してください ツール > コード > REST APIの生成…ツールバーから。
以下の REST API ウィンドウで、 プロバイダー を選択した状態で APIタイプこれにより、APIドキュメントだけでなく、サービス（ロジック）のプログラミングを支援するサーバーサンプルコードも生成できます。

Select the REST Resource to be generated

生成するRESTリソースを選択してください

コードを生成するRESTリソースを選択してください。
ジェネレーターは、に保存されたテンプレートを使用します。テンプレートディレクトリ コード生成に使用します。テンプレートを編集するか、別のディレクトリをテンプレートディレクトリとして選択できます。
チェックしてください APIドキュメントの生成選択されたRESTリソースの使用方法を示すHTMLファイルを生成するため。おそらく、生成されたAPIドキュメントをウェブサイトに公開し、サービスの利用者がそのドキュメントを参照してサービスへのアクセス方法を学ぶようにするつもりです。
APIドキュメントに表示される会社名を入力してください。
サービスのベースURLを入力してください。
確認してください サンプルを生成サービスのプログラミング方法を学べるソースコードを生成するため。サンプルコードは豊富で情報が豊富です。そのため、ゼロからプログラミングするのではなく、サンプルコードを生成して内容を変更し、ご自身のニーズに合わせることを強くお勧めします。
コードの出力パスを入力してください。

Output path entered

出力パスが入力されました

クリックしてください生成。チェックされた/チェックされていないオプションによって、出力ディレクトリに以下のフォルダが表示される場合があります：

フォルダ	説明
doc	APIドキュメント。サービスの利用者がAPIを学ぶためにドキュメントを確認できるように、APIドキュメントをウェブサイトに公開してください。
lib	生成されたコードを動作させるためには、クラスパスにGoogle Gsonライブラリが必要です。https://code.google.com/p/google-gson/ からライブラリを手動でダウンロードし、libフォルダに配置してください。
sample_src	クライアントおよびサーブレットのサンプルコード。クライアントとしてのアクセス方法と、プロバイダとしてリクエストに応答する方法を示しています。コードをコピーして、自身のサービスロジックで内容を埋め込むことを強くお勧めします。
src	通信モデルのソースコード。ファイルの内容を変更しないでください。それ以外の場合、コードが正しく動作しなくなる可能性があります。

生成されたファイルの説明

パート4：生成されたREST APIの使い方？

RESTfulサービスの利用者は、RESTリソースにアクセスするためのAPIコードを取得するために、一連のステップを経る必要があります。

利用者のためのステップバイステップガイド

ステップ1：APIドキュメントを訪問する

サービスプロバイダが公開したサービスのAPIドキュメントを訪問してください。APIドキュメントは次のようになります：

REST API documentation

REST APIドキュメント

ステップ2：REST APIモデルXMLをダウンロードする

APIドキュメントを読むことで、RESTリソースの使い方を学ぶことができます。APIコードを取得するには、APIドキュメントの下部までスクロールしてください。ページ下部にあるREST APIモデルXMLファイルのダウンロードリンクをクリックしてください。

Download REST API model XML

REST APIモデルXMLのダウンロード

ステップ3：Visual Paradigmのダウンロードとインストール

公式ウェブサイトからVisual Paradigmをダウンロードしてください。インストールして実行してください。

ステップ4：XMLファイルのインポート

ツールバーから プロジェクト > インポート > XML… を選択してください。

ステップ5：インポート設定の指定

XMLインポート ウィンドウで、XMLファイルのパスを入力し、 インポート.

The Import XML window

XMLインポートウィンドウ

ステップ6：クラス図の開く

図面タブで、XMLファイルをインポートして作成されたクラス図をダブルクリックしてください。プロジェクトブラウザ

Open the class diagram

クラス図を開く

ステップ7：通信モデルの確認

これで、RESTリソースの通信モデルが確認できます。以下のようになります：

The communication model

通信モデル

ステップ8：APIコードの生成

ツールバーから ツール > コード > REST APIの生成… を選択してください。

ステップ9：APIタイプとしてコンシューマを選択

REST APIウィンドウを選択してくださいConsumerとしてAPIタイプ.

Select Consumer to be API Type

APIタイプとしてConsumerを選択してください

ステップ10：RESTリソースを選択して生成を設定する

コードを生成するRESTリソースを選択してください。

Select the REST Resource to be generated

生成するRESTリソースを選択してください

をスキップする会社フィールドはプログラミングでは実際には必要ありません。サービスのベースURLを入力してください。チェックしてくださいサンプルを生成サービスにアクセスする方法を学べるソースコードを生成します。コードの出力パスを入力してください。

Output path entered

出力パスが入力されました

ステップ11：コードを生成して使用する

をクリックしてください生成。チェック/アンチェックされたオプションによって、出力ディレクトリに以下のフォルダが表示される場合があります：

フォルダ	説明
lib	生成されたコードを動作させるには、クラスパスにGoogle Gsonライブラリが必要です。https://code.google.com/p/google-gson/ からライブラリを手動でダウンロードし、libフォルダに配置してください。
sample_src	サービスにアクセスする方法を示すサンプルコードです。コードをコピーし、独自のアプリケーションロジックで書き換えることを強くお勧めします。
src	通信モデルのソースコードです。ファイルの内容を変更しないでください。それ以外の場合、コードが正しく動作しなくなる可能性があります。

生成されたファイルの説明

結論

Visual Paradigmは、REST APIの設計、文書化、生成のための包括的で効率的なソリューションを提供します。UMLクラス図を活用することで、開発者はAPIリソース、リクエスト/レスポンスボディ、さまざまなシナリオを視覚的にモデル化でき、開発プロセス全体で明確さと一貫性を確保できます。

Visual ParadigmをREST API開発に使用する主な利点

視覚的デザイン：UML図を用いてREST APIを視覚的に設計できる機能により、プロセスがより直感的でアクセスしやすくなり、チームメンバーおよびステークホルダーの学習コストが低下します。
一貫性：UMLモデル（単一の真実のソース）からコードと文書を生成することで、Visual Paradigmは設計、実装、文書化の間の一貫性を保証します。
文書生成：包括的なAPI文書を自動生成することで、大幅な時間短縮が可能になり、文書が実際の実装と常に同期した状態を保つことができます。
コード生成：プロバイダーおよびコンシューマーの両方のサンプルコードを生成することで、開発を加速し、API通信モデルの実装における誤りの可能性を低減できます。
双方向ワークフロー：XMLモデルのエクスポートおよびインポートが可能になることで、サービスプロバイダーとコンシューマー間のスムーズな連携が実現され、両者がAPIについて同じ理解を持つことを保証します。
複数のシナリオ対応：異なるステータスコードを持つ複数の応答シナリオをモデル化できる機能により、さまざまなユースケースやエラー状態をカバーする包括的なAPI設計が可能になります。

Visual Paradigmを活用したREST API設計のベストプラクティス

URIには名詞を使用する：URIを設計する際は、アクションを表す動詞ではなく、リソースを表す名詞を使用する。
明確な説明を定義する：リソース、パラメータ、例について明確な説明を提供することで、コンシューマーがAPIの使い方を正しく理解できるようにする。
すべてのシナリオをモデル化する：成功時とエラー時の応答シナリオを両方含めることで、APIの振る舞いを包括的に把握できるようにする。
例を提供する：常にリクエストとレスポンスの例を提供し、期待されるペイロード構造を明確に示す。
文書を生成・レビューする：常にAPI文書を生成・レビューし、設計内容を正確に反映していることを確認する。
サンプルコードを使用する：実装の出発点として生成されたサンプルコードを活用し、ゼロから始めるのではなくする。

将来の考慮事項

ソフトウェア開発の環境が継続的に進化する中で、視覚的モデル化とコード生成をサポートするVisual Paradigmのようなツールは、ますます価値が高まっていくでしょう。これらはチームが：

一貫性を維持する大規模なチームや複雑なシステムにわたって
開発時間を短縮する自動化を通じて
品質を向上させる手動翻訳エラーを排除することで
協力を強化する異なるステークホルダー間で

Visual ParadigmをREST API設計および生成に採用することで、組織はAPI開発プロセスを簡素化し、より高品質なAPIを提供し、API利用者に良い体験を提供できます。

参考文献

REST APIの概要：REST APIの概念とVisual ParadigmによるREST API生成サポートの概要
UMLを用いたREST APIのモデリング：Visual ParadigmにおけるUMLクラス図を用いたREST API設計の詳細ガイド
UMLを用いたREST APIの設計方法：UML図を用いたREST API設計の実践的な手順
UMLからREST APIを生成する方法：UMLモデルからREST APIコードを生成するためのステップバイステップの手順
生成されたREST APIの使い方：生成されたREST APIコードの使用に関する利用者向けガイド
Visual Paradigmのチュートリアル：Visual Paradigmの使い始めに役立つチュートリアルのコレクション
Visual Paradigm YouTubeチャンネル：動画リソースとデモ
Visual Paradigmのノウハウ：ヒント、テクニック、解決策を備えた知識ベース
Visual Paradigmサポート：サポートおよび連絡先情報