ハイパーメディア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 entry")]
public function onGet()

または：

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

または：

$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\MyProject\Resource\Page\Rels;

use BEAR\ApiDoc\ApiDoc;

class Index extends ApiDoc
{
}

JSON Schemaのフォルダをwebに公開します：

ln -s var/json_schema public/schemas

DocblockコメントとJSON Schemaを使って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モジュールも利用可能です。