DirectCloud-BOX APIを実行しようとしてハマった事を書き溜めます。
私の技術及び、ドキュメント読解力がないためか、結構ハマったので次にトライする人のためになればと思い書き記します。
キャンペーンや時期によって条件や改修が行われている可能性があるため、本記事の投稿日、更新日を考慮の上お読みください。
また、DirectCloud-BOX のAPI連携により広がるファイル共有・活用の可能性 - 開発～利用までの期間短縮、業務の効率化を実現しよう！ が開催中です。
ハマった事
ドキュメントの記載間違い① service, service_keyの発行手順に間違いがある
service, service_key service、service_keyの発行につきましては、お問合せ窓口よりご連絡ください。
とあったため、問い合わせたが
管理画面のここから出力できるとの返信を貰った。ここからすぐにAPIが利用可能
APIドキュメントにAPIエンドポイントの記載がない
APIのパスは記載されているが、プロトコル、ドメイン、接頭パスなどの情報が記載されていなかった。
力技（辞書総当たり）で探索した結果、https://api.directcloud.jp/ にAPIパスをくっつけると動作する事がわかった。
jsonBodyでリクエストすると失敗する
postmanで検証していたのですが、form requestだと通るようです。
ドキュメントの記載間違い② langのデフォルト値がjpn＆＆設定効かない
些細な問題だが、アクセストークンの発行によるとデフォルトがengのようだが実際はjpnで返ってくる。
また、headerにlangを設定しても反映されない。試行錯誤の結果、headerではなくクエリストリングで追加すると動いた
ドキュメントの記載間違い③ ブラウザを変えてもアクセストークン使えるよ
新規発行されアクセストークンはセキュリティのため60日間のみ有効です。有効期限切れのアクセストークンは破棄され、新規に発行されます。アクセストークンは接続環境毎に発行されますので、例えば、chromeで発行されたアクセストークンはIEでは使用できません。
と書いてある。しかし、実際のところアクセストークンさえ発行すれば、ブラウザは関係ない（そもそもPostman/curlで発行しているのでブラウザではない）。
AWSALBというクッキーが書かれるので、おそらくスタティックロードバランサーに配慮したクッキーへの記載だろうと推測するが、アクセストークンには関係なかった
ドキュメントの記載間違い④ requiredって書いてあるけど実はoptional
フォルダリストの照会によると、nodeは必須フィールドのようだが実際はoptionalで指定しなくても取得できる。
この事に気づくまで、WebUI上でどこからノードIDを取得できるか本当に悩んだ。（Chromeのネットワークタブから探した）
ひょっとして、と思いnodeなしでリクエストした結果、ルートフォルダからのフォルダリストの取得に成功した
ここが惜しい！
アクセストークンを作成するのにID、パスワード、サービスシークレット（？）が必要
ユーザの生パスワードを貰わないと、アクセストークンが生成できない。
ユーザはサードパーティーアプリに生パスワードを渡す必要がある。そのパスワードが保存したり悪用されないかはサードパーティーアプリの開発者の良心に任される事になる。
一般的にはOAuthを利用して、生パスワードを渡さずに、サードパーティーアプリに権限を移譲するのが無難である。
また、サービスシークレットも必須なため、生パスワードを第三者のサーバーに送らないようにクライアントサイド実装したくとも、サービスシークレットを埋め込む必要がある
追記
CORSがフルオープンだったので、サービスシークレット的なのは公開OKで、ブラウザ上で好きに使ってOKという事かもしれない。
（しかし、そうすると次項の問題がより顕著になる気がする）
アクセストークンにスコープをつける事ができない
基本的にフルパーミッションのアクセストークンしか生成できないので
- 特定のディレクトリのみにアクセスできるサービス
- 書き込みだけできるサービス
- 読み込みだけできるサービス
のようなものができない （開発者のさじ加減ではできるが、ユーザが安心して使えるという意味でできない）
仮にアクセストークンが漏洩したときに、影響範囲が全ファイルに及んでしまうというのはサービス運営上のリスクになる
また、開発者の良心に全てを任せる事になるため、スコープを設定できるとベター
追記
これらの問題を回避するには、API連携用のユーザと共有フォルダを組み合わせてスコープを絞る必要があるため、利用開始時に手作業が発生する。
（ここを自動化するには管理者アクセストークン（スコープはなし）が必要）
あとがき
私のスキルが足りないせいか、すごいハマってしまいましたが
SaaS提供者が、サードパーティの共有ストレージを使用できるという試みはS3やGCPと差別化できより良い。
反面、もう少しセキュリティ周りを調整できたらリトライしたいと思いました。