tl;dr

最近, Kibela の記事をローカルマシン上の vim で書きたいという欲求が高まってきました. 前職で Backlog でも同じことを考えて daimyo というツールを作ったので, 同じことを Kibela でもやりたいと思い, ゴールデンウィーク中に Kibela の Web API を調査した際のメモ集大成です.

Kibela Web API について

現在は, ベータ版として提供されているとのことです.

docs.kibe.la

そして, RESTful Web API ではなく, GraphQL で提供されている点が特徴でもあり, 個人的に新たな境地に足を踏み入れることになった点です. GraphQL については, 以下の記事が勉強になりました.

employment.en-japan.com

但し, 上記の記事ですが, 昭和インフラおじさんの筆者の理解度はまだ 2 割程度となっており, まだまだ勉強が必要ですが, とにかく手を動かしてみることにしました.

大変申し訳ございませんが, 本記事では GraphQL の詳細や, Kibela Web API 上の GraphQL のクエリの詳細については触れることが出来ませんので, 何卒, ご容赦下さい.

Kibela Web API を使う

とりあえずはトークンの発行

Kibela の設定＞個人設定＞個人用アクセストークンにて, 「アクセストークンの作成」をクリックしてアクセストークンを発行します.

f:id:inokara:20190506090831p:plain

とりあえずは GraphiQL

アクセストークンを発行したページに「Web API console」へのリンクがあるので, このリンクを踏むと GraphiQL という GraphQL 用の IDE ページにアクセスすることが出来ます. 以下のようなページです.

f:id:inokara:20190506091252g:plain

とりあえず, 記事の一覧, 新規作成, 更新, 削除という基本的な操作を GraphiQL で試してみたいと思います.

とりあえずは query と mutation

query はデータの取得
mutation はデータの更新

この二つは GraphQL の基本のようなので, これだけはとりあえず覚えておきたいと思います.

記事一覧を取得する

記事一覧を取得するクエリは, 以下の通りです.

query {
  notes (first: 1) {
    edges {
      cursor
      node {
        id
        title
        content
        folderName
        groups {
          name
        }
      }
    }
    totalCount
  }
}

以下のようなレスポンスが返ってきます.

{
  "data": {
    "notes": {
      "edges": [
        {
          "cursor": "MQ",
          "node": {
            "id": "QmxvZy80NA",
            "title": "aaaaaa",
            "content": "foo",
            "folderName": null,
            "groups": [
              {
                "name": "Home"
              }
            ]
          }
        }
      ],
      "totalCount": 8
    }
  }
}

以下は, GraphiQL での操作例です.

f:id:inokara:20190506091252g:plain

記事を新規作成する

記事を新規作成するクエリは以下の通りです.

mutation($title: String!, $content: String!){
  createNote(input: { title: $title, content: $content, coediting: false, groupIds: [] }) {
    clientMutationId
  }
}

そして, このクエリに対して, 以下のような変数を渡すことが出来ます.

{ "title": "たたたたいとる", "content": "ここここんてんつ" }

以下のようなレスポンスが返ってきます.

{
  "data": {
    "createNote": {
      "clientMutationId": null
    }
  }
}

以下は, GraphiQL での操作例です.

f:id:inokara:20190506093030g:plain

記事を更新する

記事を更新するクエリは以下の通りです.

mutation($id: ID!, $old_title: String!, $old_contents: String!, $new_title: String!, $new_contents: String!) {
  updateNote(input: {
    id: $id, 
    baseNote: {title: $old_title, content: $old_contents, coediting: false, groupIds: []},
    newNote: {title: $new_title, content: $new_contents, coediting: true, groupIds: []},
    draft: false }) {
    clientMutationId
  }
}

このクエリに対しても, 以下のような変数を渡すことが出来ます.

{
  "id": "QmxvZy80OQ",
  "old_title": "たたたたいとる1",
  "old_contents": "ここここんてんつ1",
  "new_title": "たたたたたたたたたたたたいとる2",
  "new_contents": "こここここここここんんてんつ2"
}

以下は, GraphiQL での操作例です.

f:id:inokara:20190506094319g:plain

ちなみに, id は更新の対象となる記事の ID になるんだと思いますが, 更新にあたっては, baseNoteに更新対象記事の属性 (title や content 等) まで, クエリに書かないといけない点が冗長だなあと感じました. なぜ, ID だけではだめなのか, 何らかの理由があるとは思うのですが気になるところです.

記事を削除する

記事を削除するクエリは以下の通りシンプルです.

mutation($id: ID!) {
  deleteNote(input: { id: $id }) {
    clientMutationId
  }
}

クエリに直接 ID を書くよりも変数として渡す方が良いということに記事を書きながら気付きました. ということで, 以下のように変数を書きます.

{"id": "QmxvZy80OQ"}

以下は, GraphiQL での操作例です.

f:id:inokara:20190506094849g:plain

以上

GraphQL 予備知識ゼロで Kibela Web API を触ってみました. ゴールデンウィークの初日あたりは GraphQL が本当にわからなすぎて心が折れかけましたが, 終盤になるとやっと雰囲気をつかめるようになりました. 今度は Ruby クライアントで色々と操作出来るように頑張ってみようと思います.