クイックスタート：API でエントリーを取り出す

このページでは、Hako CMS に申し込み、記事を 1 件書いて公開し、その記事を API で取り出すところまでを一通りやってみます。かかる時間は 5 分ほどです。

最後には、次のような JSON が手元に返ってきます。

{
  "items": [
    {
      "sys": { "id": "hello", "contentType": "posts", "version": 1 },
      "title": "はじめての記事"
    }
  ],
  "total": 1
}

用意するもの

• メールを受け取れるメールアドレス
• curl が使える端末、またはブラウザ

1. 申し込む

無料のプランで申し込みます。料金はかかりません。

1. 申し込みの画面を開きます。
2. ［メールアドレス］、［お名前］、［パスワード（契約・お支払いの画面用）］を入れます。
3. ［CMS のアドレス］に、英小文字・数字・ハイフンで名前を入れます（例：「my-site」）。この名前が、あなたの環境のアドレス https://<ホスト名>.hakocms.net になります。
4. ［利用規約に同意します］にチェックを入れます。
5. ［申し込む］を押します。

［申し込む］の下に「ボットでないことを確認しています」と表示されているときは、確認が済むと自動で申し込みます。確認には 10 秒ほどかかることがあります。

入れたメールアドレスに、管理画面のパスワードを決めるためのメールが届きます。

2. 管理画面のパスワードを決める

1. 届いたメールのリンクを開きます。
2. ［パスワード］と［パスワード（確認）］に、管理画面で使うパスワードを入れます。
3. ［パスワードを設定してログイン］を押します。

管理画面（https://<ホスト名>.hakocms.net/admin）が開き、「まだスペースがありません」と表示されます。

申し込みの画面のパスワードと、管理画面のパスワードは別のものです。どちらも保存しておいてください。

3. スペースを作る

スペースは、1 つのサイトやアプリのエントリーをまとめる単位です。

1. ［スペースを作成］を押します。
2. ［スペース名］に「ブログ」、［スペース ID］に「blog」と入れます。
3. ［作成］を押します。

「まだコンテンツタイプがありません」と表示されます。

4. コンテンツタイプを作る

コンテンツタイプは、エントリーを入れる箱です。ここでは、ひな形を使って「記事」を作ります。

1. ［コンテンツタイプを作成］を押します。
2. ［コレクション］が選ばれていることを確かめて、［次へ］を押します。
3. ［コンテンツタイプ名］に「記事」、［エンドポイント］に「posts」と入れて、［次へ］を押します。
4. ［ブログ記事］を選んで、［作成］を押します。

タイトル、説明、アイキャッチ、本文のフィールドを持つ「記事」ができ、記事の一覧の画面が開きます。［エンドポイント］に入れた「posts」が、API の URL に入ります。

5. 記事を書いて公開する

1. ［新規作成］を押します。
2. ［タイトル］に「はじめての記事」、［本文］に好きな文を入れます。
3. 右の［エントリー ID（省略すると自動で付ける）］に「hello」と入れます。空のままにすると、ID が自動で付きます。
4. ［公開］を押します。

「公開しました」と表示され、記事の状態が［公開中］になります。

6. API キーを発行する

API でエントリーを取り出すには、API キーが要ります。

1. 左のメニューの［API キー］を押します。
2. ［名前］に「quickstart」と入れて、［発行］を押します。

hako_ で始まる API キーが表示されます。

キーはこのときに 1 度だけ表示されます。 コピーして、安全な場所に保存してください。

発行したキーの権限は［読み取り］です。公開中のエントリーを読むことだけができます。

7. API でエントリーを取り出す

curl で取り出します。<ホスト名> は手順 1 で決めた名前、<API キー> は手順 6 で保存したキーに置き換えてください。

curl https://<ホスト名>.hakocms.net/api/v1/content/posts \
  -H "Authorization: Bearer <API キー>"

次のように返ります（日時は省いています）。

{
  "items": [
    {
      "sys": {
        "id": "hello",
        "contentType": "posts",
        "version": 1
      },
      "title": "はじめての記事",
      "body": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [{ "type": "text", "text": "Hako CMS から配信しています。" }]
          }
        ]
      }
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

JavaScript なら、fetch で同じように取り出せます。どのオリジンからでも呼べます。

const res = await fetch("https://<ホスト名>.hakocms.net/api/v1/content/posts", {
  headers: { Authorization: "Bearer <API キー>" },
});
const { items } = await res.json();
console.log(items[0].title); // はじめての記事

1 件だけ取り出すときは、URL の最後にエントリー ID を付けます（/api/v1/content/posts/hello）。

これで、最初のエントリーを API で取り出せました。

うまくいかないとき

返ってきたもの	原因	直し方
401 unauthorized	API キーがない、または違う	Authorization: Bearer のあとに、hako_ で始まるキーをそのまま入れているか確かめます。キーをなくしたら、［API キー］の画面で新しく発行します
404 not_found	コンテンツタイプかエントリーが見つからない	URL の posts が、手順 4 の［エンドポイント］と同じか確かめます。エントリーが［公開中］になっているか確かめます。下書きのエントリーは、読み取りのキーでは返りません
［申し込む］を押しても先に進まない	利用規約のチェックがない、または確認が終わっていない	「申し込むには、利用規約への同意が要ります」と出たら、［利用規約に同意します］にチェックを入れます。「ボットでないことを確認しています」と出ているときは、そのまま待ちます

それでも直らないときは、応答の X-Request-Id ヘッダーの値を添えて、問い合わせてください。

次にやること

• エントリーを取り出す：body は JSON で返ります。URL に ?richText=html を付けると、HTML の文字列で受け取れます
• 絞り込む、並べる、ページに分ける