APIとスキーマ

APIは、同じ構造のコンテンツをまとめる単位です。ブログとお知らせで入力項目や用途が違う場合は、別々のAPIとして作成します。APIの作成や設定変更にはオーナー権限が必要です。

形式を選ぶ

オブジェクト形式は一覧を返しません。例えばprofileをオブジェクト形式で作ったら、SDKではgenko.apis.profile.get()を使います。

APIを作る

1. 作成先のワークスペースを開き、APIの作成画面へ進みます。
2. 名前・エンドポイント・必要に応じて説明を入力します。
3. リスト形式またはオブジェクト形式を選びます。
4. スキーマに必要なフィールドを追加して、作成を完了します。

API名は管理画面で見分けるための名前です。エンドポイントは配信URLの一部になります。ブログならblogのように、用途がわかる名前を付けてください。同じワークスペース内で重複するエンドポイントは使えません。

https://api.genko.me/v1/your-workspace/blog

スキーマを設計する

スキーマは「どんな項目を入力できるか」を決めます。タイトル・本文だけで始めて、用途に合わせて画像・カテゴリ・著者などを追加できます。

種類ごとの値や設定はフィールドで確認できます。本文にすべての情報を埋め込むより、検索・表示に使う情報を別フィールドにすると扱いやすくなります。

スキーマを変更する

対象APIのスキーマ画面で項目を編集し、「変更を保存」から差分を確認して反映します。保存した変更は配信レスポンスにも反映されます。

変更前に、利用中のサイトがどのフィールドを参照しているか確認してください。特にID・種類の変更やフィールドの削除は、既存の表示コードに影響します。必須項目を増やすと、既存の記事を次に保存するときに入力が必要になることがあります。

アプリ側では次の順に更新します。

1. CLIのpullで型を同期します。
2. 追加・変更したフィールドに合わせて表示コードを更新します。
3. 既存の記事も取得し、値が未入力の場合の表示を確認します。
4. アプリの型チェックと表示確認を行います。

pullはデータ移行を行いません。既存の記事に新しい値を補う作業は、管理画面で行ってください。

API設定

対象APIの設定画面では、プレビューURLやWebhookなどを設定します。プレビューはサイト側の受け取り処理、Webhookは通知先の処理も必要です。

APIを削除すると、配下のコンテンツも削除されます。そのAPIを利用しているサイトやアプリへの影響を確認してから操作してください。