ハイパーメディア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()

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\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モジュールも利用可能です。