PortalDots一部機能のWebAPI化(まずは企画情報取得APIから)

[toshi-bp]

背景

従来のPortalDotsでは、以下の流れでWebサイトに掲載する企画情報の取得を行なっていました。

1. スタッフモードにログイン
2. 企画情報をcsvでダウンロード
3. csvを自身の手でjsonに変換
4. webサイトに掲載

企画情報取得APIを作成することにより上で示した工程を全てコード上で行うことができ、開発者ファーストなシステムにより一歩近づくと考えられます。

内容(イメージ)

僕の経験値がかなり浅いこともあり、至らない部分が多々あると思われます。ご容赦ください。
なお、REST APIを想定してイメージを書いてます。

• APIトークンを生成する機能の作成(とりあえずスタッフのみ使用できるようにすることを想定？)
• 企画情報を取得してjsonとして返すためのURI及び機能を作成(URIはGETで/v1/kikaku/みたいなものをイメージ)
• ポータルに接続できなくなるかもしれない可能性を想定してjsonデータをダウンロードするためのURIもあった方が良いと思われます。

余裕があればベータ版的なものでもいいので導入を検討していただけると嬉しいです。
(可能なら僕も開発に参加したいと考えています。)

[SofPyon]

@toshi-bp

提案ありがとう！こういう機能欲しかった！

機能としては、microCMSのようなヘッドレスCMSに近いものになりそうですね。API設計も、microCMSのドキュメントが参考になりそうです。
開発者ファーストなシステムにしていきたい…！

下記長文になってしまってすみません！

---

書いてくれた「内容(イメージ)」の感じで概ね実装できそうな気がします。実装する場合は下記のような方針になりそうですかね。

下記をベースに、検討・実装をお願いできないでしょうか？（可能であればで問題ないです！）
大変そうであれば、タスクを細かく分割して、個別のIssueとして作成するのがよさそうです。

実装方針

• 各フォームごとにAPIトークンを生成できる。
  • forms テーブルに、新しく api_token というカラムを追加する。
  • スタッフモード › 申請管理 › フォームの閲覧とAPIトークンの管理 という権限を新しく作った方がよさそう。APIトークンの作成・閲覧・削除は、この権限を持ったユーザーでないとできないようにするイメージ。
• APIが返すJSON内のフィールド名を、各設問ごとに指定できるようにする。たとえば、企画名なら kikakuName など。
  • questions テーブルに、新しく api_field_name みたいなカラムを作成し、そこに kikakuName のような文字列が入るイメージ。
• GET /api/v1/forms/{formId}/answers でそのフォームの全回答が入ったJSONを返す。
• GET /api/v1/forms/{formId}/answers/{answerId} で、特定の回答IDの内容が入ったJSONを返す。
• 上記のAPIを叩くには、HTTPリクエストヘッダーに X-PORTALDOTS-FORM-API-TOKEN を含める。ここに、上記で生成したAPIトークンを入れる。
• フォームの回答が編集されたことを検知できるように Webhook も設定できるようにすると良いかも？さすがに不要？

レスポンスJSONイメージ

※ 全回答が入ったJSONでは、下記が配列となるイメージ。
※ 回答した企画の情報が circle の中に入るイメージ。

{
    "answer_id": 1,
    "answer_details": {
        "kikakuName": "食品サンプル展示会",
        "kikakuGroupName": "食品サンプル同好会",
        "kikakuDescription": "食品サンプルの展示・販売",
        "kikakuLongDescription": "こんにちは！私たちは食品サンプルの作成に関する研究を行なっているサークルです！門点祭では私たちが制作してきた食品サンプルを展示いたします！"
    },
    "circle": {
        "id": 1,
        "name": "食品サンプル展示会",
        "name_yomi": "しょくひんさんぷるてんじかい",
        "group_name": "食品サンプル同好会",
        "group_name_yomi": "しょくひんさんぷるどうこうかい"
    },
    "created_at": "2021-10-19T07:17:46.919Z",
    "updated_at": "2021-10-19T07:17:46.919Z"
}

検討ポイント

• 1フォームごとにつきAPIトークンは1つだけ生成できるようにする？複数の方が良い？
• 回答ごとに、APIのレスポンスに含めるかどうかを設定できた方がよさそう？（一部の回答を非公開にしたいというケースもありそう）
• できれば、フォームにアップロードされた画像も一緒にAPIで取得できると良いかも？

---

ちなみに、PortalDotsのバージョンの付け方ポリシーというものがあります。今年中にこの機能をリリースするには「マイナーバージョンアップでマイグレーションが必要な新しい機能を追加するが、マイグレーションを実施しない場合、その新しい機能を無効化する」という方針で実装する必要がありそうです。
（※このリンクはPortalDotsの開発チームのメンバーのみアクセス可能です）

[SofPyon]

ちなみに、今回は「Webサイトに掲載する企画情報の取得」が主な目的だけど、この機能を応用すれば、いろいろできそうな気がしてきた。

• 備品貸出申請が新しく申請されたら、備品貸出システムに申請データが自動で登録される
• 場所希望申請のデータが、場所抽選システムに自動で登録される
• 新しい参加登録が提出されたら、自動でその企画用の参加登録領収書が印刷される
• 食品調理従事者申請が提出されたら、各従事者ごとに渡す検便容器のラベルが自動で作成される
• 車両入構申請が提出されたら、その車両用の入構許可証ファイルが自動で作成される

などなど、、、

[toshi-bp]

@SofPyon
ぜひ実装させてください！(まずはtokenカラムを付け足すところからやっていきます。)

[toshi-bp]

ちなみに、今回は「Webサイトに掲載する企画情報の取得」が主な目的だけど、この機能を応用すれば、いろいろできそうな気がしてきた。

• 備品貸出申請が新しく申請されたら、備品貸出システムに申請データが自動で登録される
• 場所希望申請のデータが、場所抽選システムに自動で登録される
• 新しい参加登録が提出されたら、自動でその企画用の参加登録領収書が印刷される
• 食品調理従事者申請が提出されたら、各従事者ごとに渡す検便容器のラベルが自動で作成される
• 車両入構申請が提出されたら、その車両用の入構許可証ファイルが自動で作成される

などなど、、、

おぉ...
僕はここまで思い浮かびませんでした。さすがsofpyonさんです。。
大型アップデートに向けて、これらの機能も後々実装していきたいですね。

[SofPyon]

@toshi-bp

ぜひ実装させてください！(まずはtokenカラムを付け足すところからやっていきます。)

ありがとう！めっちゃ助かります！

大型アップデートに向けて、これらの機能も後々実装していきたいですね。

いろいろ書いてみたけど、流石にオーバースペックな気がしてきました。
そこまで検討する必要ないかもっていう感じがしますね。。