ハイパーメディアAPI
HAL
BEAR.SundayはHALハイパーメディア(application/hal+json
)APIをサポートします。
HALのリソースモデルは以下の要素で構成されます。
- リンク
- 埋め込みリソース
- 状態
HALは従来のリソースの状態のみを表すJSONにリンクの_links
と他リソースを埋め込む_embedded
を加えたものです。HALはAPIを探索可能にしてそのAPIドキュメントをAPI自体から発見することができます。
Links
以下は有効なHALの例です。自身(self
)のURIへのリンクを持っています。
{
"_links": {
"self": { "href": "/user" }
}
}
Link Relations
リンクにはrel
(relation)があり、どの様な関係でリンクされているかを表ます。HTMLの<link>
タグや<a>
タグで使われるrel
と同様です。
{
"_links": {
"next": { "href": "/page=2" }
}
}
HALについてさらに詳しくはhttp://stateless.co/hal_specification.htmlをご覧ください。
リソースクラス
アノテーションでリンクを貼ったり他のリソースを埋め込むことができます。
#[Link]
リンクが静的なものは#[Link]
属性で表し、動的なものはbody['_links']
に代入します。宣言的に記述できる#[Link]
属性が良いでしょう。
#[Link(rel="user", href="/user")]
#[Link(rel="latest-post", href="/latest-post", title="latest post entrty")]
public function onGet()
or
public function onGet() {
// 権限のある場合のみリンクを貼る
if ($hasCommentPrivilege) {
$this->body += [
'_links' => [
'comment' => [
'href' => '/comments/{post-id}',
'templated' => true
]
]
];
}
}
#[Embed]
他のリソースを静的に埋め込むには@Embed
アノテーションを使い、動的に埋め込むにはbody
にリクエストを代入します。
#[Embed(rel="todos", src="/todos{?status}")]
#[Embed(rel="me", src="/me")]
public function onGet(string $status): static
or
$this->body['_embedded']['todos'] = $this->resource->uri('app://self/todos');
APIドキュメント
Curiesの設置されたAPIサーバーをAPIドキュメントサーバーにもすることができます。APIドキュメントの作成の手間や実際のAPIとのずれやその検証、メンテナンスといった問題を解決します。
サービスするためにはbear/api-doc
をインストールしてBEAR\ApiDoc\ApiDoc
ページクラスを継承して設置します。
composer require bear/api-doc
<?php
namespace MyVendor\MyPorject\Resource\Page\Rels;
use BEAR\ApiDoc\ApiDoc;
class Index extends ApiDoc
{
}
Json Schemaのフォルダをwebに公開します。
ln -s var/json_schema public/schemas
DocblockコメントとJson Shcemaを使ってAPIドキュメントが自動生成されます。ページクラスは独自のレンダラーを持ち$context
の影響を受けないで、人のためのドキュメント(text/html
) をサービスします。$context
の影響を受けないのでApp
、Page
どちらでも設置可能です。
CURIEsがルートに設置されていれば、API自体がハイパーメディアではない生JSONの場合でも利用可能です。リアルタイムに生成されるドキュメントは常にプロパティ情報やバリデーション制約が正確に反映されます。
デモ
git clone https://github.com/koriym/Polidog.Todo.git
cd Polidog.Todo/
composer install
composer setup
composer doc
docs/index.mdにAPI docが作成されます。
ブラウズ可能
HALで記述されたAPIセットはヘッドレスのRESTアプリケーションとして機能します。
WebベースのHAL BrowserやコンソールのCURLコマンドでWebサイトと同じようにルートからリンクを辿って始めて全てのリソースにアクセスできます。
Siren
Sirenハイパーメディア(application/vnd.siren+json
)をサポートしたSirenモジュール も利用可能です。