Node.js
api
TypeScript
DocBase

TypeScript対応のDocBase APIクライアント 'node-docbase-sdk'の実装方法

概要

TypeScript対応のDocBase APIクライアントをnpmで公開してみたの記事でnpmに公開したDocBase APIクライアントで、全てのDocBase APIをTypeScriptで実装できましたので、改めて記事にすることにしました。

あと、サンプルコードも公開いたします。

node-docbase-sdkについて

node-docbase-sdkは、情報共有サービスのDocBase (https://docbase.io/) API用のライブラリです。 TypeScriptに対応しており、TypeScriptで実装したい開発者向けのライブラリです。

https://www.npmjs.com/package/node-docbase-sdk

API対応表

下記、DocBase API(以下、API)とnode-docbase-sdk(以下、SDK)の対応表です。
2018年1月3日時点で公開されているAPIに対して網羅してみました。

API-になっているものは、公開APIに存在しません。

DocBaseAPIの公式マニュアルはこちら

API SDK Resource 操作 Method URI Params
メモ 取得 GET /teams/:domain/posts/:id -
メモ 一覧 GET /teams/:domain:/posts q: string 検索文字列
page: number ページ
per_page: number 表示数
メモ 作成 POST /teams/:domain/posts -
メモ 更新 PATCH /teams/:domain/posts/:id -
メモ 削除 DELETE /teams/:domain/posts/:id -
- - チーム 取得 GET - -
チーム 一覧 GET /teams 条件検索できない
- - チーム 作成 POST - -
- - チーム 更新 PATCH - -
- - チーム 削除 DELETE - -
- - グループ 取得 GET - -
グループ 一覧 GET /teams/:domain/groups 条件検索できない
- - グループ 作成 POST - -
- - グループ 更新 PATCH - -
- - グループ 削除 DELETE - -
- - タグ 取得 GET - -
タグ 一覧 GET /teams/:domain/tags 条件検索できない
- - タグ 作成 POST -
- - タグ 更新 PATCH -
- - タグ 削除 DELETE -
- - コメント 取得 GET -
- - コメント 一覧 GET -
コメント 作成 POST /teams/:domain/posts/:id/comments
- - コメント 更新 PATCH -
コメント 削除 DELETE /teams/:domain/comments/:id
- - ファイル 取得 GET -
- - ファイル 一覧 GET -
ファイル 作成 POST /teams/:domain/attachments
- - ファイル 更新 PATCH -
- - ファイル 削除 DELETE -

実装方法の解説

DocBaseオブジェクトの準備

  • DocBaseオブジェクトを使ってをDocBase APIとやりとりします。
  • const docBase: DocBase = new DocBase(DOC_BASE_API_TOKEN, TEAM_NAME)docBaseオブジェクトを用意してください。
  • DOC_BASE_API_TOKENには、DocBaseのアクセストークンを設定してください。アクセスートークンの取得方法は、以下、公式マニュアルを参照してください。
  • process.env.DOC_BASE_API_TOKENを取得するには、コマンド実行時に環境変数としてDOC_BASE_API_TOKENを設定してください。
    • コマンド実行例: $ DOC_BASE_API_TOKEN=*** node .
  • TEAM_NAMEは、domainを指定してください
    • 例えば、https://hoge.docbase.ioというURLでDocBaseを利用している場合、const TEAM_NAME='hoge'です。
docBaseオブジェクトの用意
// An access token
const DOC_BASE_API_TOKEN = process.env.DOC_BASE_API_TOKEN;
const TEAM_NAME = 'TEAM_NAME';

const docBase: DocBase = new DocBase(DOC_BASE_API_TOKEN, TEAM_NAME);

Memo conditional search / メモ条件検索

  • qに検索文字列を入力します。
  • 検索オプションについてはこちらを参照してください。

https://help.docbase.io/posts/92984

メモ条件検索
  const condition: MemoCondition = <MemoCondition>{};
  condition.q = 'query';
  condition.page = 1;
  condition.perPage = 20;
  const reponse: DocBaseResponse = await docBase.memos.list(condition);

Memo detail / メモ詳細

https://help.docbase.io/posts/97204

  const id = 1;
  const reponse: DocBaseResponse = await docBase.memos.find(id);

Memo create / メモ投稿

https://help.docbase.io/posts/92980

  const memo: Memo = <Memo>{};
  memo.title = 'title';
  memo.body = 'title';
  memo.draft = false;
  memo.notice = false;
  memo.scope = DisclosureScopes.PRIVATE;
  const reponse: DocBaseResponse = await docBase.memos.create(memo);

Memo update / メモ更新

https://help.docbase.io/posts/92981

  const memo: Memo = <Memo>{};
  memo.id = 1;
  memo.title = 'title';
  memo.body = 'body';
  memo.draft = false;
  memo.notice = false;
  memo.scope = DisclosureScopes.PRIVATE;
  const reponse: DocBaseResponse = await docBase.memos.update(memo);

Memo delete / メモ削除

https://help.docbase.io/posts/92982

  const id = 1;
  const reponse: DocBaseResponse = await docBase.memos.delete(id);

My team list / 所属チーム取得

https://help.docbase.io/posts/92977

  const reponse: DocBaseResponse = await docBase.teams.list();

Comment post / コメント投稿

https://help.docbase.io/posts/216289

  const memoId = 1;
  const entity: Comment = <Comment>{};
  entity.memo_id = memoId;
  entity.body = 'COMMENT';
  entity.notice = false;
  const response: DocBaseResponse = await docBase.comments(memoId).create(entity);

Comment delete / コメント削除

https://help.docbase.io/posts/216290

  const id = 1;
  const memoId = 1;
  const response: DocBaseResponse = await docBase.comments(memoId).delete(id);

Group list / グループ取得

https://help.docbase.io/posts/92978

  const response: DocBaseResponse = await docBase.groups.list();

Tag list / タグ取得

https://help.docbase.io/posts/92979

  const response: DocBaseResponse = await docBase.tags.list();

File upload / ファイルアップロード

https://help.docbase.io/posts/225804

  const file: File = <File>{};
  file.file_path = '/Users/yfujisawa/Desktop/etc.txt'; 
  const splitPath: string[] = filePath.split('/');
  const fileName = splitPath[splitPath.length - 1];
  file.name = fileName;
  const response: DocBaseResponse = await docBase.files.create(file);

サンプルコード(TypeScript)

import { DocBase } from 'node-docbase-sdk/lib/DocBase';
import { DocBaseResponse } from 'node-docbase-sdk/lib/DocBaseResponse';
import { HttpStatus } from 'node-docbase-sdk/lib/enums/HttpStatus';
import { MemoCondition } from 'node-docbase-sdk/lib/conditions/MemoCondition';
import { Memo } from 'node-docbase-sdk/lib/entities/Memo';
import { DisclosureScopes } from 'node-docbase-sdk/lib/enums/DisclosureScopes';
import { Comment } from 'node-docbase-sdk/lib/entities/Comment';
import { Team } from 'node-docbase-sdk/lib/entities/Team';
import { Group } from 'node-docbase-sdk/lib/entities/Group';
import { File } from 'node-docbase-sdk/lib/entities/File';
import { Tag } from 'node-docbase-sdk/lib/entities/Tag';

// Get DocBaseAPI Token from cli.
// ex.
//   $ DOC_BASE_API_TOKEN=<DOC_BASE_API_TOKEN> node .
const DOC_BASE_API_TOKEN = process.env.DOC_BASE_API_TOKEN;
const TEAM_NAME = 'TEAM_NAME';
const KEYWORD = 'DOCBASE_API_TEST';

const docBase: DocBase = new DocBase(DOC_BASE_API_TOKEN, TEAM_NAME);

// コメント削除API
// @see https://help.docbase.io/posts/216290
async function deleteComment(entity: Comment) {
  console.log('== START deleteComment ==');
  const response: DocBaseResponse = await docBase.comments(entity.memo_id).delete(entity.id);
  console.log(`=== response: deleteComment===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// コメント投稿API
// @see https://help.docbase.io/posts/216289
async function postComment(memoId: number) {
  console.log('== START postComment ==');
  const entity: Comment = <Comment>{};
  entity.memo_id = memoId;
  entity.body = 'DOCBASE_API_TEST_COMMENT';
  entity.notice = false;
  const response: DocBaseResponse = await docBase.comments(memoId).create(entity);
  console.log(`=== response: postComment===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// グループ取得API
// @see https://help.docbase.io/posts/92978
async function getGroups() {
  console.log('== START getGroups ==');
  const response: DocBaseResponse = await docBase.groups.list();
  console.log(`=== response: getGroups===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// タグの取得API
// @see https://help.docbase.io/posts/92979
async function getTags() {
  console.log('== START getTags ==');
  const response: DocBaseResponse = await docBase.tags.list();
  console.log(`=== response: getTags===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// ファイルアップロードAPI
// @see https://help.docbase.io/posts/225804
async function uploadFile(filePath: string) {
  console.log('== START uploadFile ==');
  const file: File = <File>{};
  file.file_path = filePath;
  const splitPath: string[] = filePath.split('/');
  const fileName = splitPath[splitPath.length - 1];
  console.log('fileName::' + fileName);
  file.name = fileName;
  const response: DocBaseResponse = await docBase.files.create(file);
  console.log(`=== response: uploadFile===`);
  console.log(response.body);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// 所属チーム取得API
// @see https://help.docbase.io/posts/92977
async function getMyTeams(): Promise<Team[]> {
  console.log('== START getMyTeams ==');
  const response: DocBaseResponse = await docBase.teams.list();
  console.log(`=== response: getMyTeams===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// メモ投稿API
// @see https://help.docbase.io/posts/92980
async function createMemo(): Promise<Memo> {
  console.log('== START createMemo ==');
  const memo: Memo = <Memo>{};
  memo.title = KEYWORD;
  memo.body = KEYWORD;
  memo.draft = false;
  memo.notice = false;
  memo.scope = DisclosureScopes.PRIVATE;
  const response: DocBaseResponse = await docBase.memos.create(memo);
  console.log(`=== response: createMemo===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// メモ更新API
// @see https://help.docbase.io/posts/92981
async function updateMemo(memoId: number): Promise<Memo> {
  console.log('== START updateMemo ==');
  const memo: Memo = <Memo>{};
  memo.id = memoId;
  memo.title = KEYWORD + '_updated';
  memo.body = KEYWORD + '_updated';
  memo.draft = false;
  memo.notice = false;
  memo.scope = DisclosureScopes.PRIVATE;
  const response: DocBaseResponse = await docBase.memos.update(memo);
  console.log(`=== response: updateMemo===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// メモ詳細取得API
// @see https://help.docbase.io/posts/97204
async function findMemo(memoId: number): Promise<Memo> {
  console.log('== START findMemo ==');
  const response: DocBaseResponse = await docBase.memos.find(memoId);
  console.log(`=== response: findMemo ===`);
  console.log(response);
  console.log('======');
  if (response.status === HttpStatus.OK) {
    return response.body;
  }
  throw new Error(response.body);
}

// 複数メモ取得API
// @see https://help.docbase.io/posts/92984
async function searchMemos(keyword: string): Promise<Memo[]> {
  console.log('== START searchMemos ==');
  const condition: MemoCondition = <MemoCondition>{};
  condition.q = keyword;
  condition.page = 1;
  condition.per_page = 20;
  const response: DocBaseResponse = await docBase.memos.list(condition);
  console.log(`=== response: searchMemos===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return response.body.posts;
  }
  throw new Error(response.body);
}

// メモ削除API
// @see https://help.docbase.io/posts/92982
async function deleteMemo(memoId: number): Promise<boolean> {
  console.log('== START deleteMemo ==');
  const response: DocBaseResponse = await docBase.memos.delete(memoId);
  console.log(`=== response: deleteMemo===`);
  console.log(response);
  console.log(`======`);
  if (response.status === HttpStatus.OK) {
    return true;
  }
  throw new Error(response.body);
}

async function main() {
  try {
    const teams: Team[] = await getMyTeams();
    const groups: Group[] = await getGroups();
    const tags: Tag[] = await getTags();
    const createdMemo: Memo = await createMemo();
    const updatedMemo: Memo = await updateMemo(createdMemo.id);
    const memoDetail: Memo = await findMemo(updatedMemo.id);
    const memoList: Memo[] = await searchMemos(memoDetail.title);
    for (const memo of memoList) {
      if (memo.title === 'DOCBASE_API_TEST_updated') {
        console.log(JSON.stringify(memo));
        const comment: Comment = await postComment(memo.id);
        await deleteComment(comment);
        await deleteMemo(memo.id);
      } else {
        throw new Error(JSON.stringify(memo));
      }
    }
  } catch (error) {
    throw error;
  }
}

// == Main ==
main().catch((error) => {
  console.log(error);
});
// ====

サンプルプロジェクト

上記、サンプルコードをすぐに動作確認できるようにGitHubにサンプルプロジェクトも用意しました。ぜひ、ご活用ください。

サンプルプロジェクトはこちら