NILTO Developer APIリファレンス

Download OpenAPI specification:Download

Developer APIを利用して、NILTOで作成したコンテンツデータを取得することができます。

基本情報

APIベースURL

https://cms-api.nilto.com/v1

APIキー認証

認証のためにAPIキーをリクエストヘッダーに含めて送信してください。 スペース設定のAPIキー画面で取得することができます。

key value
X-NILTO-API-KEY APIキー

APIキーには、公開コンテンツのみ取得できるAPIキーと、下書きも含めて取得できるAPIキーがあります。用途に合わせて使い分けてください。

使用例

コンテンツ一覧を取得

基本

モデルがnewsであるコンテンツ一覧を50件目から最大10件を取得

/contents?model=news&offset=50&limit=10

上記のレスポンス例:

{
  "total": 345,
  "offset": 50,
  "limit": 10,
  "data": [
    {
      "_id": 1234567890,
      "_model": "news",
      "_title": "Hello World",
      "_created_at": "2023-01-23T04:50:00Z",
      "_updated_at": "2023-01-23T04:50:00Z",
      "_published_at": "2023-01-23T04:50:00Z",
      "_status": "published",
      "field1": "value1",
      "field2": "value2"
    },]
}

コンテンツ参照フィールドcategoryで、IDが1234567890のコンテンツを参照しているコンテンツ一覧を取得

/contents?category[eq]=1234567890

日時を指定してコンテンツ一覧を取得

日時はISO 8601拡張形式で指定します。

更新日時が日本時間で2023年1月23日4時よりも新しいコンテンツの配列を取得

/contents?_updated_at[gt]=2023-01-23T04:00:00+09:00

上記と同じ日時をUTC時間(2023年1月22日19時)で指定する場合

/contents?_updated_at[gt]=2023-01-22T19:00:00Z

キーワード検索でコンテンツ一覧を取得

特定のフィールドに指定したキーワードを含むコンテンツ一覧を取得する場合、containsフィルターを使用します。

フレキシブルテキストフィールドbodykeywordを含むコンテンツの配列を取得

/contents?body[contains]=keyword

複数のキーワードをAND検索

/contents?body[contains]=keyword1,keyword2

ブロック内フィールドに対して条件指定してコンテンツ一覧を取得

ブロック内のフィールドは、ブロックLUIDとフィールドLUIDを.で連結して指定できます。

例: ブロックblock内のフィールドtextの内容がabcであるコンテンツ一覧を取得

/contents?block.text[eq]=abc

参照コンテンツのフィールドに対して条件指定してコンテンツ一覧を取得

注意: この仕様は今後実装予定です。現在はご利用いただけません。

参照しているコンテンツのフィールドは、フィールドLUIDを.で連結して指定できます。

例: コンテンツ参照フィールドcategoryで参照しているコンテンツのフィールドkeyの内容がreleaseであるコンテンツ一覧を取得

/contents?category.key[eq]=release

特定のコンテンツを取得

コンテンツIDが1234567890のコンテンツを取得

/contents/1234567890

上記のレスポンス例:

{
  "_id": 1234567890,
  "_model": "news",
  "_title": "Hello World",
  "_created_at": "2023-01-23T04:50:00Z",
  "_updated_at": "2023-01-23T04:50:00Z",
  "_published_at": "2023-01-23T04:50:00Z",
  "_status": "published",
  "field1": "value1",
  "field2": "value2"
}

コンテンツ参照の深度制限を変更してコンテンツを取得

depthパラメータを使用することで、参照するコンテンツのオブジェクトを取得する再帰深度を変更することができます。指定より深い参照は、オブジェクトではなくコンテンツIDになります。

コンテンツ参照フィールドのオブジェクトを取得しない場合

/contents/1234567890?depth=0

上記のレスポンス例:

{
  "_id": 1234567890,
  "content_reference": 2345678901
}

コンテンツ参照フィールドのオブジェクトを1階層まで取得する場合(デフォルト動作)

/contents/1234567890?depth=1

上記のレスポンス例:

{
  "_id": 1234567890,
  "content_reference": {
    /* 参照1階層目 */
    "_id": 2345678901,
    "content_reference": 3456789012
  }
}

コンテンツ参照フィールドのオブジェクトを3階層まで取得する場合

/contents/1234567890?depth=3

上記のレスポンス例:

{
  "_id": 1234567890,
  "content_reference": {
    /* 参照1階層目 */
    "_id": 2345678901,
    "content_reference": {
      /* 参照2階層目 */
      "_id": 3456789012,
      "content_reference": {
        /* 参照3階層目 */
        "_id": 4567890123,
        "content_reference": 5678901234
      }
    }
  }
}

詳細

IDとLUID

APIのリクエストパラメーターで、特定のオブジェクトを指定するとき、IDもしくはLUIDを使用します。

IDはシステムが定義する、グローバルでユニークなIDです。ユーザーが変更することはできません。

LUID (Locally Unique Identifier) はユーザーが定義するIDです。モデル/ブロックのLUIDはスペース内でユニークです。フィールドLUIDはモデル/ブロック内でユニークです。

オブジェクトごとの指定方法は以下になります。

オブジェクト 指定方法 変更 確認方法
モデル LUID モデル詳細ページ > 基本情報ダイアログ
ブロック LUID ブロック詳細ページ > 基本情報ダイアログ
フィールド LUID モデル(ブロック)詳細ページ > フィールド詳細ペイン
コンテンツ ID 不可 コンテンツ詳細ペイン > API出力確認ダイアログ

アーカイブされたコンテンツ・メディア

アーカイブされたコンテンツは、Developer APIで取得することはできません。 アーカイブされたコンテンツやメディアを参照しているフィールドは、値が空になります。

フィールド種類ごとのレスポンスデータ

フレキシブルテキスト

flexibletext_field[format]=htmlを指定した場合(デフォルト動作)

"flexibletext_field": "<div><h2>abcedf</h2><p>abcedf</p><ul><li>abcedf</li></ul></div>"

flexibletext_field[format]=textを指定した場合

"flexibletext_field": "abcedf\r\nabcedf\r\nabcedf"

1行テキスト

"singleline_field": "foobar"

複数行テキスト

"multiline_field": "foobar\r\nfoobar"

ブーリアン

"boolean_field": true

単一選択

"singleselect_field": "value"

日時

"datetime_field": "2023-01-23T04:50:00Z"

メディア

"media_field": {
  "url": "https://cms-assets.nilto.com/spaces/1234567890/media/2345678901/_/abc.png",
  "alt": "alternative text"
}

コンテンツ参照

"reference_field": {
  "_id": 2345678901,
  "_title": "Hello World2",
  "_created_at": "2023-01-23T04:50:00Z",
  "_updated_at": "2023-01-23T04:50:00Z",
  "_published_at": "2023-01-23T04:50:00Z",
  "_status": "published",
  "singleline_field": "foobar"
}

繰り返し

繰り返しは、フィールドの集合であるオブジェクトの配列で表現されます。

"repeat_field": [
  {
    "singleline_field": "foo",
    "boolean_field": true
  },
  {
    "singleline_field": "foobar",
    "boolean_field": false
  },
  {
    "singleline_field": "foobarbaz",
    "boolean_field": true
  }
]

組み合わせ

組み合わせは、ブロックのデータであるオブジェクトの配列で表現されます。 ブロック内のluidは指定したLUIDです。fieldsはブロック内フィールドです。

"combination_field": [
  {
    "luid": "block_a",
    "fields": {
      "singleline_field": "foo",
      "boolean_field": true
    }
  },
  {
    "luid": "block_b",
    "fields": {
      "datetime_field": "2023-01-23T04:50:00Z",
      "singleselect_field": "value"
    }
  },
  {
    "luid": "block_a",
    "fields": {
      "singleline_field": "foobar",
      "boolean_field": false
    }
  }
]

ブロック(モデルに直接組み込んだ場合)

"block": {
  "singleline": "foobar",
  "boolean": true
}

フィールド種類ごとのフィルター

コンテンツ一覧取得APIのフィルターについて、指定できる値は以下になります。

フィールド種類 [eq] [in] [lt] [lte] [gt] [gte] [contains]
フレキシブルテキスト N/A N/A N/A N/A N/A N/A 文字列
1行テキスト 文字列 文字列 N/A N/A N/A N/A 文字列
複数行テキスト 文字列 文字列 N/A N/A N/A N/A 文字列
ブーリアン true/false N/A N/A N/A N/A N/A N/A
単一選択 文字列 文字列 N/A N/A N/A N/A N/A
日時 N/A N/A 日時 日時 日時 日時 N/A
メディア N/A N/A N/A N/A N/A N/A N/A
コンテンツ参照 コンテンツID コンテンツID N/A N/A N/A N/A N/A
繰り返し N/A N/A N/A N/A N/A N/A N/A
組み合わせ N/A N/A N/A N/A N/A N/A N/A
ブロック N/A N/A N/A N/A N/A N/A N/A

一定時間あたりのリクエスト制限

Developer APIの品質を担保するため、リクエストは1分あたり1000回までに制限されます。この制限はAPIキーごとに適用されます。

この制限を超えたリクエストは429エラーになります。このとき、次のリクエストが可能になるまでの秒数がretry-afterヘッダーで返されます。

既知の不具合

Developer APIに関する既知の不具合は以下のとおりです。

  • orderパラメータでフィールドを2つ以上指定するとエラーになる。
  • 日時フィールドの値をDeveloper APIで取得すると、9時間進んだ値になる。
  • _created_at, _updated_at, _published_atに対して、[gt]などを使ってUTC時間で条件設定すると、エラーになることがある。
    • この不具合を回避するためには、最後のZを省略してください。例: _created_at[gt]=2024-02-22T03:00:00

/contents

コンテンツの配列を取得

指定した条件に合うコンテンツの配列を取得します。

Authorizations:
X-NILTO-API-KEY
query Parameters
select
string
Example: select=_id,description

データを取得するフィールドを指定します。カンマ区切りで複数指定できます。省略するとすべてのフィールドを取得します。

depth
integer [ 0 .. 3 ]
Default: 1
Example: depth=3

参照するコンテンツのオブジェクトを取得する深度を指定します。

order
string
Example: order=pickup,-_title

並べ替える基準とするフィールドのLUIDを指定します。カンマ区切りで複数指定できます。降順にするにはLUIDの先頭に-をつけます。

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=10

取得する件数の上限を指定します。

offset
integer >= 0
Default: 0
Example: offset=10

何件目から取得するかを指定します。

model
string
Example: model=blog,news

取得対象とするモデルのLUIDを指定します。カンマ区切りで複数指定できます。省略するとすべてのモデルのコンテンツを取得対象とします。

lang
string
Example: lang=ja

取得したいコンテンツの言語を指定します。省略するとデフォルト言語の内容を取得します。

{field_luid}[format]
string
Default: "html"
Enum: "html" "text"
Example: {field_luid}[format]=text

フレキシブルテキストのデータ形式を指定します。

{field_luid}[eq]
string
Example: {field_luid}[eq]=value

フィールドの内容が指定した値と一致するコンテンツのみ取得します。

{field_luid}[in]
string
Example: {field_luid}[in]=value1,value2,value3

フィールドの値が指定した値のいずれかに一致するコンテンツのみ取得します。カンマ区切りで複数指定できます。

{field_luid}[lt]
string
Example: {field_luid}[lt]=2023-01-23T04:50:00Z

フィールドの内容が指定した値より小さいコンテンツのみ取得します。

{field_luid}[lte]
string
Example: {field_luid}[lte]=2023-01-23T04:50:00Z

フィールドの内容が指定した値以下のコンテンツのみ取得します。

{field_luid}[gt]
string
Example: {field_luid}[gt]=2023-01-23T04:50:00Z

フィールドの内容が指定した値より大きいコンテンツのみ取得します。

{field_luid}[gte]
string
Example: {field_luid}[gte]=2023-01-23T04:50:00Z

フィールドの内容が指定した値以上のコンテンツのみ取得します。

{field_luid}[contains]
string
Example: {field_luid}[contains]=keyword1,keyword2

フィールドの内容に指定した値が含まれるコンテンツのみ取得します。カンマ区切りでAND検索になります。

Responses

Request samples

curl -H 'X-NILTO-API-KEY:0000000000000000000000' \
'https://cms-api.nilto.com/v1/contents?model=news&field1[eq]=true'

Response samples

Content type
application/json
{
  • "total;": 34,
  • "offset": 20,
  • "limit": 10,
  • "data": [
    ]
}

/contents/{content_id}

コンテンツを取得

指定したIDのコンテンツを取得します。

Authorizations:
X-NILTO-API-KEY
path Parameters
content_id
required
string
Example: 1234567890

取得するコンテンツのID

query Parameters
select
string
Example: select=_id,description

データを取得するフィールドを指定します。カンマ区切りで複数指定できます。省略するとすべてのフィールドを取得します。

depth
integer [ 0 .. 3 ]
Default: 1
Example: depth=3

参照するコンテンツのオブジェクトを取得する深度を指定します。

lang
string
Example: lang=ja

取得したいコンテンツの言語を指定します。省略するとデフォルト言語の内容を取得します。

{field_luid}[format]
string
Default: "html"
Enum: "html" "text"
Example: {field_luid}[format]=text

フレキシブルテキストのデータ形式を指定します。

Responses

Request samples

curl -H 'X-NILTO-API-KEY:0000000000000000000000' \
'https://cms-api.nilto.com/v1/contents/1234567890?lang=ja'

Response samples

Content type
application/json
{
  • "_id": "1234567890",
  • "_model": "news",
  • "_title": "Hello World",
  • "_created_at": "2023-01-23T04:50:00Z",
  • "_updated_at": "2023-01-23T04:50:00Z",
  • "_published_at": "2023-01-23T04:50:00Z",
  • "_status": "published",
  • "flexibletext_field": "<div><h2>abcedf</h2><p>abcedf</p><ul><li>abcedf</li></ul></div>",
  • "singleline_field": "foobar",
  • "multiline_field": "foo\nbar",
  • "boolean_field": true,
  • "singleselect_field": "value1",
  • "datetime_field": "2023-01-23T04:50:00Z",
  • "media_field": {},
  • "repeat_field": [
    ],
  • "combination_field": [
    ],
  • "reference_field": {
    },
  • "block1": {
    },
  • "block2": {
    }
}