RESTful API ドキュメント (概説)

準備

https://example.com/powercmsx/api/ 配下のリクエストを https://example.com/powercmsx/api/index.php に渡すように設定します。パスはカスタマイズ可能です。その場合はindex.php内のパスを環境にあわせて書き換えてください。

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php [L]
</IfModule>

スコープの設定画面とモデルの編集画面で「APIを有効化」にチェックを入れることで、利用可能になります。

認証(authentication)エンドポイントについては環境変数「api_allow_login」指定のある場合に利用可能になります(初期値true)。

エンドポイントへのアクセス

authentication エンドポイントは以下のパス

/api/バージョン/authentication

それ以外のエンドポイントは以下の形のパスとなります

/api/バージョン/スコープID/モデル名/メソッド/オブジェクトID(オプション)?キー1=値1&キー2=値2...

※スペースに属さないシステムレベルのオブジェクトに対する操作の場合、スコープIDは「0」を指定します。

環境変数

idプロパティの値は「RESTfulAPI」です。

通常の config.json, AppPropertiesプラグインでの管理画面での登録のほか、アプリケーションディレクトリ直下に api-config.json に以下のようにキー : 値の形式で指定することが可能です。Webアクセスができないようにしてください。

{
    "api_allow_login" : true,
    "api_list_limit" : 25,
    "api_methods": {
        "1" : {
            "entry" : ["list", "get"]
        }
    }
}

• api_methods : スコープ・モデルに対して利用可能にするエンドポイントを制限したい場合にスコープのIDをキーにして配列で指定します。スペース 1 に対して list, getエンドポイントのみを許可する場合、以下のように指定します。

"api_methods": {
    "1" : {
        "entry" : ["list", "get"]
    }
}

※ 不特定多数がアクセスできる環境では絶対に「api_debug」「api_debug_user_id」を指定しないでください。

オブジェクトJSON

返却されるオブジェクトJSONの形は基本的に以下のフォーマットです。list/searchエンドポイントではキー「items」に配列で返却されます。

{
    "id" : "オブジェクトID",
    "カラム名1" : "カラム1の値",
    "カラム名2" : "カラム2の値"
}

リレーションを含むオブジェクトJSON

リレーションを含むオブジェクトJSONのフォーマットは以下の通りです。関連オブジェクトのさらに関連オブジェクトについては展開されません。

{
    "id" : "オブジェクトID",
    "カラム名1" : "カラム1の値",
    "数値型単一リレーションカラム" : {
        "id" : "オブジェクトID",
        "カラム名1" : "カラム1の値",
        "カラム名2" : "カラム2の値"
    },
    "複数リレーション型カラム" : [
        {
            "id" : "オブジェクトID",
            "カラム名1" : "カラム1の値",
            "カラム名2" : "カラム2の値"
        },
        {
            "id" : "オブジェクトID",
            "カラム名1" : "カラム1の値",
            "カラム名2" : "カラム2の値"
        }
    ]
}

メタデータ

オブジェクトのカラムの値やリレーションによる関連オブジェクトのカラムの値以外のデータをメタデータと呼びます。 メタデータのキーは、必ず大文字で始まります。メタデータには以下のものがあります。

バイナリデータ(ファイル)の送信

例えば、記事にバイナリ型のカラムを追加している時、以下のようにして(Data URI schemeの形式で)ファイルのデータを送信します。

{
    "id" : "オブジェクトID",
    "og_image" : {
        "Label" : "ラベルまたは代替テキスト",
        "Data" : "data:image/png;base64,..................."
    }
}

アセットと添付ファイルについては、記事などのリレーションデータとして登録できます。「Path」にはサイト・パスを「%r」として相対パスを指定します。「Path」が指定できるのはアセットのみで、添付ファイルについては保存場所は自動で設定されます。

{
    "title": "Welcome!",
    "assets": [
        {
            "file": {
                "Label" : "ラベルまたは代替テキスト",
                "Data": "data:image/png;base64,...................",
                "Path": "%r/assets/filename.png"
            }
        }
    ]
}

アセットの関連付けの解除、添付ファイルの削除には「Detach」を指定します。「id」をあわせて指定しなければなりません。
添付ファイルの場合は、そのファイルを削除、アセットの場合には、そのアセットは削除されず、関連付けのみが解除されます。数値型単一選択のリレーション型にも対応しています。

{
    "title": "Welcome!",
    "assets": [
        {
            "id":23,
            "Detach":true
        }
    ]
}

contactモデルの confirm/submitエンドポイントに送信するときは、ファイル名、設問のベースネームを付けて送信します。

{
    "Identifier": "contact_us",
    "Language": "ja",
    "Permalink":"https:\/\/localhost\/01\/contact\/website_contact_us.html",
    "website_your_name": "野田純生",
    "website_email": "webmaster@alfasado.jp",
    "website_subject": "テスト投稿",
    "website_message": "テスト投稿です",
    "website_privacy_policy": "agree",
    "attachmentfiles": [
        {
            "name": "ファイル名.docx",
            "basename": "website_attachment1",
            "file": {
                "Data": "data:application\/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,............"
            }
        }
    ]
}

ステータス(status)に指定可能な値

ステータスには数値以外に文字列でも指定できます。環境変数「status_text」に指定がある場合はテキストで返却されます。

有効期限対応指定のあるモデルの場合

• 0 : 「Draft」(下書き)
• 1 : 「Review」(レビュー)
• 2 : 「Approval Pending」(承認待ち)
• 3 : 「Reserved」(公開予約)
• 4 : 「Publish」(公開)
• 5 : 「Ended」(終了)

有効期限対応指定のないモデルの場合

• 1 : 「Disable」(無効)
• 2 : 「Enable」(有効)

insert, updateメソッドにおけるワークフローの利用

insert, updateでワークローを利用するには以下のルールでオブジェクトJSONを指定します。モデルがワークフローに対応していて、そのスコープでワークフローが設定されていることが必要です。

• user_id : 承認依頼または差し戻すユーザーのID
• status : 異なる権限グループのユーザーへ渡す時は、そのユーザーが指定できるステータス以下の値
• Workflow : 「approval(承認依頼)」または「remand(差し戻し)」
• Message : ワークフロー通知に含めるメール用のメッセージ

{
    "user_id"  : ユーザーのID,
    "status"   : ユーザーに応じたステータス,
    "Workflow" : "approval",
    "Message"  : "メールに含めるメッセージのテキスト",
}

ワークフロー対応モデルのステータスの数字は以下の通りです。

• 0 : 下書き
• 1 : レビュー
• 2 : 承認待ち
• 3 : 公開予約
• 4 : 公開
• 5 : 終了

権限グループによって指定できるステータスの最大値は以下の通りです(カッコ内は異なるグループのユーザーへ渡す時に指定する値)。

• 作成者(creator) : 0 (0)
• レビュワー(reviewer) : 1 (1)
• 公開者(publisher) : 5 (2)

ワークフローの設定がない時、ワークフローで渡すことのできるユーザー以外のIDを指定した時、上記のステータスより大きな値の数字を渡したときは権限エラーとなります。

{
    "status": 403,
    "message": "Permission denied."
}

insert, update メソッドでのリビジョンの指定

リビジョンを指定するには「rev_type」「rev_object_id」を指定します。rev_type=1 が自動保存、rev_type=2 がリビジョンです。

{
    "rev_type" : 1または2,
    "rev_object_id" : マスタのID
}

マスタが存在しない時、マスタとリビジョンのスコープが違うときはエラーとなります。マスタを update メソッドでリビジョンに変更することはできません。

プラグインによる RESTful APIへのメソッドの追加

プラグインによって RESTful APIへメソッドを追加することができます。

config.json

{
    "label": "RESTfulAPIEndPoint",
    "id": "restfulapiendpoint",
    "component": "RESTfulAPIEndPoint",
    "description": "Provides RESTful API Custom EndPoint.",
    "version": "1.0",
    "author": "Alfasado Inc.",
    "author_link": "https://alfasado.net/",
    "api_methods": {
        "v1" : {
            "custom_end_point": {
                "component": "RESTfulAPIEndPoint",
                "method": "custom_end_point",
                "permission": "create_entry",
                "allowed" : [
                    "PUT",
                    "POST"
                ]
            }
        }
    }
}

RESTfulAPIEndPoint.php

<?php
require_once( LIB_DIR . 'Prototype' . DS . 'class.PTPlugin.php' );

class RESTfulAPIEndPoint extends PTPlugin {

    function __construct () {
        parent::__construct();
    }

    function custom_end_point ( $app ) {
        // $app は PTRESTfulAPIv1 クラス
        // $app->id は 'RESTfulAPI'
        // $app->json_error( 'An error has occurred.', 403 );
        // $app->json_error( 'An error has occurred(%s).', 'Error Messaage', 403 );
        $json = [];
        $app->print_json( $json );
    }
}

フックとコールバック

• フックは管理画面と同様に動作します。
• insert, update, delete 時には管理画面の save, deleteメソッド実行時のコールバックが呼ばれます。
• ファイルのパブリッシュ時は publish_callbacks 関連のコールバックが呼ばれます。

モデル restfulapi に対する「pre_response」コールバックを登録することで、レスポンスを返す直前のデータの配列にアクセスできます。

$app->init_callbacks( 'restfulapi', 'pre_response' );
$callback = ['name' => 'pre_response'];
$this->run_callbacks( $callback, 'restfulapi', $json );

第3引数 &$json をカスタマイズすることで、そのデータを返します。

function pre_response ( $cb, $app, &$json ) {
}