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プロパティの値は「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の形は基本的に以下のフォーマットです。list/searchエンドポイントではキー「items」に配列で返却されます。
{
"id" : "オブジェクトID",
"カラム名1" : "カラム1の値",
"カラム名2" : "カラム2の値"
}
リレーションを含むオブジェクト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_text」に指定がある場合はテキストで返却されます。
有効期限対応指定のあるモデルの場合
有効期限対応指定のないモデルの場合
insert, updateでワークローを利用するには以下のルールでオブジェクトJSONを指定します。モデルがワークフローに対応していて、そのスコープでワークフローが設定されていることが必要です。
{
"user_id" : ユーザーのID,
"status" : ユーザーに応じたステータス,
"Workflow" : "approval",
"Message" : "メールに含めるメッセージのテキスト",
}
ワークフロー対応モデルのステータスの数字は以下の通りです。
権限グループによって指定できるステータスの最大値は以下の通りです(カッコ内は異なるグループのユーザーへ渡す時に指定する値)。
ワークフローの設定がない時、ワークフローで渡すことのできるユーザー以外のIDを指定した時、上記のステータスより大きな値の数字を渡したときは権限エラーとなります。
{
"status": 403,
"message": "Permission denied."
}
リビジョンを指定するには「rev_type」「rev_object_id」を指定します。rev_type=1 が自動保存、rev_type=2 がリビジョンです。
{
"rev_type" : 1または2,
"rev_object_id" : マスタのID
}
マスタが存在しない時、マスタとリビジョンのスコープが違うときはエラーとなります。マスタを update メソッドでリビジョンに変更することはできません。
プラグインによって 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 );
}
}
モデル 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 ) {
}