Edited at

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

More than 1 year has passed since last update.


概要

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にサンプルプロジェクトも用意しました。ぜひ、ご活用ください。

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