コラボフロー REST APIを利用するためのお話

[**コラボフロー Advent Calendar 2022**](https://qiita.com/advent-calendar/2022/collaboflow) **11日目です。**

コラボフローの導入をご検討いただいている方の中には、「**コラボフロー REST APIを使えば色々できそうじゃないか？**」と思っていいただいている方もいらっしゃることと思います。

また、4日目の「[**コラボフロー REST APIって叩いてみた？**](https://qiita.com/nonbin/items/87639a44b684b40947a7 "コラボフロー REST APIって叩いてみた？")」を読んだ皆さんの中には、実際に自社のシステムやサービスとの連携にどう使えるかを考えられた方もいらっしゃるのではないでしょうか？

そんな時、一番最初の難関となるのが、「**コラボフロー REST APIって、どうやって使うの？**」ということではないかと思います。

今回は、コラボフロー REST APIを利用する敷居を下げるお話しをます。

## コラボフロー REST APIとは

簡単に説明すると、「**コラボフロー REST APIとは、HTTPリクエストをコラボフローに送信し、対応するデーターを結果として得る機能**」になります。

つまり、HTTPリクエストを送信し、応答を受け取ることができれば、「**どのようなツールであれサービスであれ、利用することができる**」ということになります。
コラボフローのデーターを利用したいシステムで、HTTPリクエストを送信する機能を組み込んだり、HTTPリクエストを送信することができるアプリケーションを導入してHTTPリクエストを実行させることで利用できます。

```plantuml
他システム->コラボフロー : HTTPリクエスト（このデーターをくださいなー）
コラボフロー->他システム : 応答（はいよー）
```

:::note
**コラボフロー REST APIは、HTTPリクエストを送信することで利用できます。**
**HTTPリクエストを送信し、応答を受信することができる、アプリケーションや開発言語など、何を使っても機能します。**
:::

## コラボフロー REST APIでリクエストを送信するときは認証情報が必要

[リファレンスページ](http://docs.collaboflow.com/api-docs/#/Document/getDocumentOverview "コラボフロー REST APIリファレンス")に記載の通り、コラボフロー REST APIを利用するためには**認証情報が必要**になります。

コラボフロー REST APIのURLをWebブラウザのURL欄に打ち込んで送信すると、「不明なユーザーによるアクセスです。」というエラーが返ります。

```plantuml
他システム->コラボフロー : HTTPリクエスト（私に認証情報などない！）
コラボフロー->他システム : 応答（あんた誰？）
```

```plantuml
他システム->コラボフロー : HTTPリクエスト（私は認証情報あるよー）
コラボフロー->他システム : 応答（どうぞどうぞ！）
```

:::note warn
**コラボフロー REST APIでリクエストを送信するときは、必ず認証情報をセットで送る必要があります。**
**認証情報がないリクエストは受付されません。**
:::

## Webブラウザ上で実行するJavaScriptに認証情報を書いてはいけない

コラボフロー REST APIの認証情報は、Base64でエンコードしますが、テキストデーターであることに違いはありません。
仕組み上、Base64エンコードされた認証情報の全文が分かっていれば、[リファレンスページ](http://docs.collaboflow.com/api-docs/#/Document/getDocumentOverview "コラボフロー REST APIリファレンス")の内容と組み合わせることで**容易にデーターを取得する**ことができます。

このため、WebブラウザでJavaScriptを使ったコラボフロー REST APIでのデーター取得は**危険**です。

:::note alert
**JavaScriptのソースに書いてはいけない情報は以下の通りです。**
* **コラボフローで発行したAPIKey**
* **Base64でエンコードした認証情報**

**リファレンスページもWebサイトになりますので、「動作確認で使用した認証情報やAPIKeyは、本運用のシステムでは使わない」ように注意してください。**
:::

## JavaScriptAPIを利用したコラボフローのカスタマイズでは、安全にコラボフロー REST APIを利用できる

JavaScriptAPIでコラボフローのカスタマイズをする場合は、**コラボフロー REST API用の関数**を使用して安全に利用することができます。

ただし、安全に利用できる代わりに**制限**があります。
それは、コラボフロー REST API用の関数でリクエストした場合の認証は、**コラボフローにログインしているユーザーになる**ということです。
このため、ログインしているユーザーが管理者権限を持たない場合、グループやユーザーといった組織のデーターを取得することはできません。
また、申請のデーターに関しても、取得できるのはログインしているユーザーが申請したデーターなどに制限されます。

```plantuml
Webブラウザー->コラボフロー : コラボフロー REST API関数（私の申請データーをくださいな）
コラボフロー->Webブラウザー : 応答（はいどうぞー）
```

```plantuml
Webブラウザー->コラボフロー : コラボフロー REST API関数（私に○○さんの申請データーをくださいな）
コラボフロー->Webブラウザー : 応答（権限がないからデーターはわたせないよー）
```

::: note
**詳しい利用方法については、コラボフローサポートサイトの「**[**コラボフロー REST APIを実行する**](https://collaboflow.zendesk.com/hc/ja/articles/360000262896 "コラボフロー REST APIを実行する")**」をご確認ください。**
:::

## ログインユーザー以外の認証情報で取得できるデーターをJavaScriptAPIのカスタムで利用したい場合

「**データーを取得し、必要に応じて加工して返す仕組み**」の、**中間システム**を用意します。

オンプレ版のコラボフローであれば、**コラボフローが稼働するサーバー**や、**自社の別のシステムのサーバー**に構築する方法が考えられます。
クラウド版であれば、**自社の別のシステムのサーバー**に構築する方法に加えて、**クラウドサービスなど**を利用して構築する方法が考えられます。

システム基盤を一から構築する場合は別ですが、普段から管理、運用しているサーバーなどに機能を加える形であれば、構築しやすいのではないかと思います。
**状況にあわせて、適切な方法で構築してください。**

```plantuml
Webブラウザー->中間システム : リクエスト（グループデーターが欲しいなー）
中間システム->中間システム : 受付（グループデーターは管理者権限が必要だね）
中間システム->コラボフロー : HTTPリクエスト（グループデーターをくださいな）
コラボフロー->中間システム : 応答（はいどうぞー）
中間システム->中間システム : データーの加工（公開してもいいデーターはこれだね）
中間システム->Webブラウザー : 応答（グループデーターを貰ってきたよー）
```

::: note warn
**構築する仕組みは、セキュリティをかけるなどの対策をしてください。**
**セキュリティをかけることが難しい場合は、返すデーターを公開しても問題ない、必要最小限の範囲に絞ることで、不要なデーターが流出しないように注意してください。**
:::
::: note
**この仕組みは、コラボフロー以外のWebを利用したシステムにも応用できます。**
:::

---

というわけで、コラボフロー REST APIを利用する敷居を下げるお話でした。