エンジニアの村山です。

この記事ではmicroCMS APIの基本構造と、そのAPIを利用するための基本的な実装方法を解説します。

この記事で例として書いてるコードはjavascriptでの実装例ですが、他の言語でも基本的な使い方は同じです。

1. microCMS APIの基本構造

エンドポイントの構成と基本概念

エンドポイントはmicroCMS上のAPIごとに作成されます。複数のAPIからデータを取得する場合は、それぞれのエンドポイントからデータを取得する必要があります。

エンドポイントは以下の形式で構成されています。

https://{サービスID}.microcms.io/api/v1/{エンドポイント}

{サービスID}: 作成したサービスごとに割り当てられる一意のID
{エンドポイント}: コンテンツの種類（APIスキーマ）を示す識別子

たとえば test-service というサービスIDで test-endpoint というエンドポイントを作成した場合、APIの基本URLは以下のようになります。

https://test-service.microcms.io/api/v1/test-endpoint

APIごとのエンドポイントは管理画面から確認できます。

基本的なリクエスト実装

以下javascriptでの基本的なリクエスト実装例です。

const getList = async () => {
  const response = await fetch('https://{サービスID}.microcms.io/api/v1/{エンドポイント}', {
    headers: {
      'X-MICROCMS-API-KEY': '{APIキー}',
      'Content-Type': 'application/json'
    }
  });
  
  const data = await response.json();
  return data;
};

レスポンスはJSON形式で返されます

{
  "contents": [
    {
      "id": "content-id",
      "createdAt": "2024-03-20T12:00:00.000Z",
      "updatedAt": "2024-03-20T12:00:00.000Z"
      ...
    },
    // ... 他の記事データ
  ],
  "totalCount": 100,
  "offset": 0,
  "limit": 10
}

{contents}はコンテンツの配列です。最大でlimitで指定した数まで返されます。(2025年1月現在、limitの初期値は10、設定できる上限は100です)
{contents[].id}はコンテンツの一意のIDです。デフォルトではコンテンツの作成時に自動生成されます。
{contents[].createdAt}はコンテンツの作成日時です。
{contents[].updatedAt}はコンテンツの更新日時です。
{contents[].{フィールドID}}その他APIに設定したフィールドの値が返されます。
{totalCount}はコンテンツの総数です。
{offset}はコンテンツの取得開始位置です。
{limit}はコンテンツの取得件数です。

2. 実践的なAPI活用テクニック

クエリパラメータの活用

microCMS APIではクエリパラメータを使用して様々な条件でコンテンツを取得することができます。

以下はよく使うクエリパラメータの例です。

フィルタリング（filters）

フィルタリングはコンテンツの取得条件を指定することができます。

具体的には特定のフィールドの値が特定の値であるコンテンツリストの取得、例えばカテゴリ情報を持つコンテンツリストを取得したい場合や、特定の著者が投稿したコンテンツリストを取得したい場合などで利用できます。

// 基本的なフィルタリング
const endpoint = `https://{サービスID}.microcms.io/api/v1/{エンドポイント}?filters=category[equals]tech`;

上記の例では、`category`フィールドが`tech`のコンテンツを取得します。

// 複数条件の組み合わせ
const complexFilter = `https://{サービスID}.microcms.io/api/v1/{エンドポイント}?filters=category[equals]tech[and]publishedAt[greater_than]2024-01-01`;

上記の例では、`category`が`tech`で、`publishedAt`が2024-01-01以降のコンテンツを取得します。

全文検索（q）

全文検索はコンテンツのテキストフィールドを検索できます。

具体的には、特定のキーワードが特定のフィールドに含まれるエントリリストを取得したい場合に利用できます。これを利用してフロントエンドにユーザーからの検索機能を実装することもできます。

// 基本的な全文検索
const endpoint = `https://{サービスID}.microcms.io/api/v1/{エンドポイント}?q=JavaScript`;

上記の例では、`JavaScript`が含まれるコンテンツを取得します。

ソート（orders）

ソートはコンテンツの取得順序を指定することができます。

// 基本的なソート
const endpoint = `https://{サービスID}.microcms.io/api/v1/{エンドポイント}?orders=publishedAt[desc]`;

上記の例では、`publishedAt`フィールドの降順でコンテンツを取得します。

ページネーション（offset/limit）

ページネーションはコンテンツの取得範囲を指定することができます。

例えば、膨大なコンテンツの中から最新情報として直近5件分のコンテンツリストを取得したり、1ページあたり10件表示するページングを実装したい場合などに利用できます。

// 基本的なページネーション
const endpoint = `https://{サービスID}.microcms.io/api/v1/{エンドポイント}?offset=0&limit=10`;

上記の例では、コンテンツを10件ずつ取得します。

ページングでの利用でさらに次のページを取得する場合は、offsetを10ずつ増やしていきます。

// 次のページを取得
const nextPage = `https://{サービスID}.microcms.io/api/v1/{エンドポイント}?offset=10&limit=10`;

3.SDK活用による開発効率化

ここまで基本的な使い方や実践的な使い方を説明してきましたが、microCMSでは開発者向けのSDKが用意されています。
https://microcms.io/features/sdk

SDKを使えばより早く、直感的にコード実装を進められます。
弊社ではWebサイトでの利用になるので主にtypescript・javascript からmicroCMSを呼び出すことが多く、microcms-js-sdk のお世話になっています。
フロントエンド向けのものだけでなく、PHP・GO・Rubyといったバックエンド向けのSDKや、スマートフォンアプリ開発用のSDKも用意されていて様々な環境からmicroCMSを活用することが容易にできます。

microCMS JavaScript SDKを使うメリット

フロントエンド目線になりますが、SDKを入れてよかったなという点をご紹介します。

1. 型安全性（TypeScript対応）

TypeScriptのサポートにより、型安全性が保証されます。
これによりコードの信頼性を高め、バグを未然に防ぐことができます。
型定義があることで、IDEの補完機能も活用できて、開発速度に寄与しています。

2. エラーハンドリングの簡略化

SDKはエラーハンドリングを簡略化するための機能を提供しています。
これによりAPI呼び出し時のエラーを効率的に管理し、適切なフィードバックを得られます。

3.メソッドチェーンによる直感的な操作

SDKはメソッドチェーンをサポートしており、直感的で読みやすいコードを書くことができます。
これにより複雑なデータ操作も簡潔に記述することができ、コードの可読性が向上します。

基本実装

microCMS JavaScript SDKをプロジェクトに導入するのは非常に簡単です。以下に基本的な実装手順を示します。

1. インストール

$ npm install microcms-js-sdk

または

$ yarn add microcms-js-sdk

2. 初期設定

import { createClient } from 'microcms-js-sdk';

export const client = createClient({
  serviceDomain: '{サービスID}',
  apiKey: '{APIキー}',
});

client を export しておくと、API連携が必要な部分で client を import するだけで良くなり一括管理しやすくなります。

3. データの取得

全件取得する場合

client
  .getAllContents({ endpoint: '{エンドポイント}' })
    .then((res) => console.log(res))
    .catch((err) => console.error(err));

クエリをつけて取得する場合

client
  .getList({
    endpoint: '{エンドポイント}',
    queries: {
      //ここに limit、offset、q、filter など、様々なクエリを設定できる
      limit: 100,
    }
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

簡単で直感的に取得できます。

これからAPIを使うという方はぜひSDKの利用を検討して欲しいです。

4.まとめ

microCMSは柔軟で強力なコンテンツ管理を可能にするツールです。

この記事では、APIの基本構造から実践的な活用方法、そしてSDKを利用した効率的な開発手法について解説しました。

• 基本構造: microCMSのAPIは、サービスIDとエンドポイントを組み合わせたURLで構成され、APIキーを使用して認証を行います。
• 実践的な活用: フィルタリング、全文検索、ソート、ページネーションなどのクエリパラメータを活用することで、必要なデータを効率的に取得できます。
• SDKの利用: microCMS JavaScript SDKを使用することで、型安全性の向上やエラーハンドリングの簡略化、メソッドチェーンによる直感的な操作が可能になります。