【ITニュース解説】Umbraco 13 to 16: API controllers

システムエンジニアを目指す初心者の皆さん、こんにちは。今回は、Webサイトやアプリケーションを開発・管理するためのオープンソースのコンテンツ管理システム（CMS）である「Umbraco」のバージョンアップ、特にバージョン13から16への移行で、APIコントローラーがどのように変わるのかを解説します。この変更は、皆さんが将来Umbracoを使った開発に携わる際に非常に重要となるポイントだ。

まず、APIコントローラーとは何かを簡単に説明する。APIは「Application Programming Interface」の略で、異なるソフトウェア同士が情報をやり取りするための仕組みだ。Webサイトでは、例えばウェブブラウザ（フロントエンド）がサーバー（バックエンド）からデータを取得したり、サーバーにデータを送ったりする際にAPIを使う。このAPIの処理内容を記述するのが「APIコントローラー」で、特定のURL（エンドポイント）へのリクエストに応じて、定義されたプログラム（メソッド）を実行する。

Umbracoの以前のバージョンであるUmbraco 13には、「UmbracoApiController」と「UmbracoAuthorizedApiController」という二種類の特別なAPIコントローラーが存在した。しかし、Umbraco 16ではこれらが廃止され、新しい方式に置き換わっている。

一つ目の「UmbracoApiController」は、皆さんが独自のWeb APIエンドポイントを作成するためのコントローラーだった。このコントローラーの最大の特徴は、コードに書かれたAPIが自動的に特定のURLに割り当てられる（ルーティングされる）ことだった。例えば、ExampleControllerというクラスでHelloWorldというメソッドを作成すると、~/Umbraco/Api/Example/HelloWorldというURLで呼び出せるようになっていた。特別な設定をしなくてもURLが決まるため、手軽にAPIを作成できるという利点があった。しかし、Umbracoの開発チームは、このコントローラーが提供する機能が通常のWeb API開発と比べてそれほど特殊ではないと判断した。そのため、Umbraco 16ではUmbracoApiControllerは廃止され、皆さんが普段使うような「通常のコントローラー」に置き換わることになる。通常のコントローラーでは、APIのURL（ルーティング）を自分自身で明示的に定義する必要がある。これは少し手間が増えるように感じるかもしれないが、より柔軟にAPIの設計ができるようになるというメリットもある。Umbracoの公式ドキュメントには、古いUmbracoApiControllerを新しい方式に移行する方法が詳しく説明されているので、そちらを参照すると良いだろう。

次に、より大きな変更となる「UmbracoAuthorizedApiController」についてだ。このコントローラーは、Umbracoの管理画面（バックオフィス）の機能を拡張するために使われることが多く、通常のWebサイトの訪問者からはアクセスできず、ログインしているUmbracoユーザーからのみ呼び出すことができるという特別なセキュリティ機能を持っていた。そのため、管理者がコンテンツを作成したり、設定を変更したりするような、バックオフィス専用のAPIエンドポイントとして利用されてきた。

Umbraco 14以降の新しいバックオフィスが登場したことにより、この「UmbracoAuthorizedApiController」も大きく変わった。新しいバックオフィスでは「Management API」というものが導入され、これがフロントエンド（管理画面のユーザーインターフェース）とバックエンド（サーバー側の処理）が通信するための標準的な方法となった。Management APIは、Umbraco 13までのバックオフィスAPIよりも、より強力で統一された形で提供されている。これまでUmbracoAuthorizedApiControllerを使っていたカスタム機能は、この新しいManagement APIに組み込む形で変更していく必要がある。

では、具体的にUmbracoAuthorizedApiControllerをManagement APIに更新する手順を見ていこう。

まず、最も基本的な変更として、APIコントローラーの「ベースクラス」を変更する。ベースクラスとは、そのコントローラーが持つ基本的な機能や振る舞いを定義する元となるクラスのことだ。Umbraco 13ではUmbracoAuthorizedApiControllerを継承していたが、Umbraco 16ではこれをManagementApiControllerBaseに変更する。これにより、Management APIとしての基本的な機能が利用できるようになる。

次に、APIコントローラーに付与されている「属性」を変更する。属性とは、クラスやメソッドに特別な意味や設定を与えるための目印のようなものだ。Umbraco 13で使われていたPluginControllerという属性は不要になり、代わりに二つの新しい属性を追加する。

一つ目はVersionedApiBackOfficeRouteだ。これは、Management APIのURLのパスを定義するための属性だ。UmbracoのManagement APIでは、/umbraco/management/api/v1/という共通のプレフィックスの後に、この属性で指定したパスが続くとる。例えば、VersionedApiBackOfficeRoute("core-content")と指定すると、APIのURLは/umbraco/management/api/v1/core-contentのようになる。UmbracoのManagement APIの規約に従い、URLのパスは小文字を使い、単語はハイフン（-）で区切るのが推奨される。

二つ目はApiExplorerSettings属性だ。この属性にはGroupNameというプロパティを設定する。これは、APIの仕様書を自動生成してくれる「Swaggerドキュメント」というツールで、皆さんの作成したカスタムAPIを特定のタイトル（例えば"ProudNerds Core"）でグループ化して表示するためのものだ。これにより、多くのAPIの中から自分のAPIを見つけやすくなる。

個々のAPIエンドポイント（メソッド）自体には大きな変更は必要ないが、いくつかの注意点がある。Umbracoは、一つのコントローラーには一つのエンドポイントのみを配置する「単一責任の原則」を推奨している。もし、一つのコントローラーに複数のエンドポイントを定義したい場合は、[HttpGet("create-new-website")]のように、HTTPメソッド属性（HttpGetなど）にユニークなパスのテンプレートを指定する必要がある。これにより、複数のエンドポイントが同じURLにならないように区別される。

また、ProducesResponseType属性を追加することで、SwaggerドキュメントにそのAPIエンドポイントがどのような種類のレスポンス（応答）を返す可能性があるかを記述できる。これはAPIを利用する開発者にとって非常に役立つ情報だ。ただし、Umbracoが内部で既に登録している400 Bad Requestや404 Not Foundといった一般的なエラーコードについては、この属性で明示的に指定しないように注意が必要だ。これを指定してしまうと、Swaggerドキュメントの生成が正しく行われなくなる可能性がある。

例えば、core-content/create-new-websiteというURLで新しいウェブサイトを作成するAPIエンドポイントを定義する場合、コントローラー全体は、VersionedApiBackOfficeRouteでcore-content/create-new-websiteと指定し、ApiExplorerSettingsでグループ名を定義する。そして、メソッドにはProducesResponseTypeで成功時の200 OK（整数のレスポンス）と、エラー時の500 Internal Server Error（ProblemDetailsというエラー詳細のレスポンス）を明示する。400 BadRequestについてはUmbracoが自動で処理するためここでは指定しない。

最後に、Management APIの「セキュリティ」についても触れておこう。デフォルトでは、Management APIのエンドポイントはUmbracoにログインしているすべてのユーザーがアクセス可能だ。しかし、特定のAPIを「管理者」のような限られたユーザーにのみアクセスさせたい場合があるだろう。その際には、Authorize属性を使う。例えば、[Authorize(Policy = AuthorizationPolicies.RequireAdminAccess)]という属性をコントローラーに追加することで、そのコントローラー内のすべてのAPIエンドポイントは、管理者権限を持つユーザーのみが利用できるようになる。これにより、よりきめ細やかなアクセス制御が可能になる。

今回の解説をまとめると、Umbraco 13から16へのAPIコントローラーの更新は、以下の二点に集約される。 UmbracoApiControllerを使っていた部分は、通常のコントローラーに置き換え、ルーティングは自分で定義するよう変更が必要だ。 UmbracoAuthorizedApiControllerを使っていた部分は、新しいManagementApiControllerBaseをベースクラスとし、VersionedApiBackOfficeRouteとApiExplorerSettings属性を追加してManagement APIに組み込む。必要に応じてAuthorize属性を使ってアクセス権限を設定することも重要だ。

これらの変更は、Umbracoがより現代的なWeb開発のプラクティスに沿った形に進化していることを示している。最初は戸惑うかもしれないが、それぞれの変更の意味を理解すれば、Umbracoでの開発がより効率的で安全になるだろう。システムエンジニアを目指す皆さんにとって、このようなバージョンアップへの対応は避けて通れない道だ。ぜひこの機会に、新しいUmbracoのAPI開発について深く学んでみてほしい。