ガイド
CDN API・Newt API

SDK

基本的な使い方
パッケージのインストール
クライアントの作成
メソッドの実行
各UID・ID・APIトークンの確認方法
スペースUID
App UID
モデルUID
コンテンツID
APIトークン
createClientのオプション
メソッドの種類
getContents: コンテンツ一覧の取得
getContent: 単一コンテンツの取得
getFirstContent: 条件に合致する最初のコンテンツの取得
getApp: App情報の取得
TypeScriptを利用する場合
事前定義されている型
戻り値の型指定

NewtではCDN API・Newt APIへのリクエスト処理を簡単に実行していただくため、newt-client-js というJavaScript SDKを用意しています。
ソースコードはGitHub上に公開されており、Newt-Inc/newt-client-js からご確認いただけます。

基本的な使い方

以下の順番で説明します。

パッケージのインストール
クライアントの作成
メソッドの実行

パッケージのインストール

npm install newt-client-js
# or
yarn add newt-client-js

クライアントの作成

CDN APIまたはNewt APIにリクエストするためのクライアントを作成しましょう。

YOUR_SPACE_UID には、リクエストを行うスペースのスペースUIDを入力してください。

CDN APIにリクエストを行う場合、YOUR_API_TOKEN にCDN APIトークンを指定し、apiType に cdn を指定します。
Newt APIにリクエストを行う場合、YOUR_API_TOKEN にNewt APIトークンを指定し、apiType に api を指定します。

import { createClient } from 'newt-client-js'

const client = createClient({
  spaceUid: 'YOUR_SPACE_UID',
  token: 'YOUR_API_TOKEN',
  apiType: 'cdn', // "cdn" または "api" を指定する
})

メソッドの実行

例えば、コンテンツ一覧の取得をする場合、以下のように実行します。
YOUR_APP_UID には、取得したいコンテンツのApp UIDを入力してください。
YOUR_MODEL_UID には、取得したいコンテンツのモデルUIDを入力してください。

const res = await client.getContents({
  appUid: 'YOUR_APP_UID',
  modelUid: 'YOUR_MODEL_UID',
})

コンテンツ一覧の取得を行った場合、返却されるレスポンスは以下のようになります。

{
  "skip": 0,
  "limit": 100,
  "total": 15,
  "items": [
    {
      "_id": "6109f05d5d18d6006af5f385",
      "_sys": {
        "createdAt": "2023-08-06T00:18:26.810Z",
        "updatedAt": "2023-08-06T08:39:45.628Z",
        "customOrder": 15,
        "raw": {
          "createdAt": "2023-08-05T05:29:09.614Z",
          "updatedAt": "2023-08-06T08:39:45.628Z",
          "firstPublishedAt": "2023-08-06T00:18:26.810Z",
          "publishedAt": "2023-08-06T08:39:45.628Z"
        }
      }
      "title": "title1",
      "description": "description1",
      ...
    },
    {
      "_id": "6109f05d5d18d6006af5f384",
      "_sys": {
        "createdAt": "2023-08-04T03:05:09.719Z",
        "updatedAt": "2023-08-06T07:42:40.902Z",
        "customOrder": 14,
        "raw": {
          "createdAt": "2023-08-03T03:21:10.832Z",
          "updatedAt": "2023-08-06T07:42:40.902Z",
          "firstPublishedAt": "2023-08-04T03:05:09.719Z",
          "publishedAt": "2023-08-06T07:42:40.902Z"
        }
      }
      "title": "title2",
      "description": "description2",
      ...
    },
    ...
  ]
}

各UID・ID・APIトークンの確認方法

スペースUID

スペース設定 > 一般から確認できます。

App UID

App設定 > 一般から確認できます。

モデルUID

モデル設定から確認できます。

コンテンツID

コンテンツ編集画面から確認できます。

APIトークン

スペース設定 > APIキーから、CDN APIトークンとNewt APIトークンをそれぞれ確認できます。

createClientのオプション

クライアントの作成では、設定をカスタマイズすることが可能です。
利用可能なオプションは以下の通りとなります。

名前	必須	デフォルト	説明
spaceUid	◯		リクエスト対象のスペースUID
token	◯		CDN APIにリクエストを行う場合はCDN APIトークン。 Newt APIにリクエストを行う場合はNewt APIトークン。
apiType		cdn	CDN APIにリクエストを行う場合は `cdn`。 Newt APIにリクエストを行う場合は `api`。
adapter		undefined	リクエストを処理するaxiosのカスタムアダプタ。詳細は axiosのRequest Config にある `adapter` をご参照ください。
retryOnError		true	デフォルトでは、レスポンスステータスが `429` または `500` の場合にリトライを行います。この挙動を無効にするには、`false` に設定します。
retryLimit		3	リトライの回数を指定します。`10` 以下の数字を指定してください。
fetch		undefined	`globalThis.fetch` や `node-fetch` などのお好きなfetch関数を指定できます。このオプションが指定された場合、axiosではなく指定されたfech関数でリクエストが実行されます。ただし、`adapter` オプションは無視され、リトライも実行されないのでご注意ください。

リクエストにaxiosを利用するか、fetchを利用するか、指定できるようになっています。

fetch オプションを指定しない場合、リクエストは axios で実行され、 adapter・retryOnError・retryLimit オプションがすべて考慮されます。
fetch オプションに値を指定すると、axiosではなく指定されたfetch関数でリクエストが実行されます。この場合、adapter オプションは考慮されず、リトライも実行されないのでご注意ください。

メソッドの種類

実行可能なメソッドは以下の4種類となります。

getContents: コンテンツ一覧の取得
getContent: 単一コンテンツの取得
getFirstContent: 条件に合致する最初のコンテンツの取得
getApp: App情報の取得

なお、具体的なユースケースについては、NewtのAPIで利用できるクエリパラメータを理解して、様々なクエリを実行するで紹介しているので、ご確認ください。

getContents: コンテンツ一覧の取得

実行例

const res = await client.getContents({
  appUid: 'YOUR_APP_UID',
  modelUid: 'YOUR_MODEL_UID',
  query: {
    '_sys.createdAt': { gt: '2023-07-01' },
    category: 'news'
  }
})

返却されるレスポンス例

{
  "skip": 0,
  "limit": 100,
  "total": 15,
  "items": [
    {
      "_id": "6109f05d5d18d6006af5f385",
      "_sys": {
        "createdAt": "2023-08-06T00:18:26.810Z",
        "updatedAt": "2023-08-06T08:39:45.628Z",
        "customOrder": 15,
        "raw": {
          "createdAt": "2023-08-05T05:29:09.614Z",
          "updatedAt": "2023-08-06T08:39:45.628Z",
          "firstPublishedAt": "2023-08-06T00:18:26.810Z",
          "publishedAt": "2023-08-06T08:39:45.628Z"
        }
      }
      "title": "title1",
      "description": "description1",
    },
    {
      "_id": "6109f05d5d18d6006af5f384",
      "_sys": {
        "createdAt": "2023-08-04T03:05:09.719Z",
        "updatedAt": "2023-08-06T07:42:40.902Z",
        "customOrder": 14,
        "raw": {
          "createdAt": "2023-08-03T03:21:10.832Z",
          "updatedAt": "2023-08-06T07:42:40.902Z",
          "firstPublishedAt": "2023-08-04T03:05:09.719Z",
          "publishedAt": "2023-08-06T07:42:40.902Z"
        }
      }
      "title": "title2",
      "description": "description2",
    },
    ...
  ]
}

メソッドで指定可能なパラメータ

名前	必須	説明
appUid	◯	リクエスト対象のApp UID
modelUid	◯	リクエスト対象のモデルUID
query		利用するクエリパラメータを指定する

クエリで指定可能なパラメータ

名前	指定形式	説明
YOUR_FIELD	-	ご自身で定義したフィールドに対してクエリをかけられます
select	文字列の配列	指定したフィールドの情報のみ取得する
order	文字列の配列	指定した順番で取得する
limit	数字	返却されるコンテンツの最大件数を指定する
skip	数字	何件のコンテンツをスキップするか指定する
depth	数字	画像フィールド・ファイルフィールド・参照フィールドで、取得するデータの階層を指定する
or	配列	いずれかの条件に合致するコンテンツを取得する（複数条件の関係を指定）
and	配列	すべての条件に合致するコンテンツを取得する（複数条件の関係を指定）

フィールドに対して指定可能な演算子
ご自身で定義したフィールドに対してフィルタをかけることで、条件に合致するコンテンツのみを取得できます。

名前	指定形式	説明
なし	-	指定した値に一致するコンテンツを取得する
ne	文字列 / 数字 / 真偽値	指定した値に一致するコンテンツを除外する
match	文字列	指定した値を含むコンテンツを取得する
in	文字列の配列 / 数字の配列	指定した要素のどれかに一致するコンテンツを取得する
nin	文字列の配列 / 数字の配列	指定した要素のどれかに一致するコンテンツを除外する
all	文字列の配列 / 数字の配列	指定した要素のすべてを含むコンテンツを取得する
exists	真偽値	指定したフィールドを持つ（持たない）コンテンツを取得する
gt	文字列 / 数字	指定した値より大きいコンテンツを取得する
gte	文字列 / 数字	指定した値以上のコンテンツを取得する
lt	文字列 / 数字	指定した値未満のコンテンツを取得する
lte	文字列 / 数字	指定した値以下のコンテンツを取得する
fmt	`text`	リッチテキストまたはマークダウンのフィールドに対して、取得形式を（HTMLではなく）テキスト形式にする

getContent: 単一コンテンツの取得

実行例

const res = await client.getContents({
  appUid: 'YOUR_APP_UID',
  modelUid: 'YOUR_MODEL_UID',
  contentId: 'YOUR_CONTENT_ID'
})

返却されるレスポンス例

{
  "_id": "6109f05d5d18d6006af5f385",
  "_sys": {
    "createdAt": "2023-08-06T00:18:26.810Z",
    "updatedAt": "2023-08-06T08:39:45.628Z",
    "customOrder": 15,
    "raw": {
      "createdAt": "2023-08-05T05:29:09.614Z",
      "updatedAt": "2023-08-06T08:39:45.628Z",
      "firstPublishedAt": "2023-08-06T00:18:26.810Z",
      "publishedAt": "2023-08-06T08:39:45.628Z"
    }
  }
  "title": "title1",
  "description": "description1",
},

メソッドで指定可能なパラメータ

名前	必須	説明
appUid	◯	リクエスト対象のApp UID
modelUid	◯	リクエスト対象のモデルUID
contentId	◯	リクエスト対象のコンテンツID
query		利用するクエリパラメータを指定する

クエリで指定可能なパラメータ

名前	指定形式	説明
select	文字列の配列	指定したフィールドの情報のみ取得する
depth	数字	画像フィールド・ファイルフィールド・参照フィールドで、取得するデータの階層を指定する

getFirstContent: 条件に合致する最初のコンテンツの取得

実行例

const res = await client. getFirstContent({
  appUid: 'YOUR_APP_UID',
  modelUid: 'YOUR_MODEL_UID',
  query: {
    title: 'title1'
  }
})

返却されるレスポンス例

{
  "_id": "6109f05d5d18d6006af5f385",
  "_sys": {
    "createdAt": "2023-08-06T00:18:26.810Z",
    "updatedAt": "2023-08-06T08:39:45.628Z",
    "customOrder": 15,
    "raw": {
      "createdAt": "2023-08-05T05:29:09.614Z",
      "updatedAt": "2023-08-06T08:39:45.628Z",
      "firstPublishedAt": "2023-08-06T00:18:26.810Z",
      "publishedAt": "2023-08-06T08:39:45.628Z"
    }
  }
  "title": "title1",
  "description": "description1",
},

メソッドで指定可能なパラメータ

名前	必須	説明
appUid	◯	リクエスト対象のApp UID
modelUid	◯	リクエスト対象のモデルUID
query		利用するクエリパラメータを指定する

クエリで指定可能なパラメータ
limit 以外のgetContentsで利用可能なパラメータを利用できます。

名前	指定形式	説明
YOUR_FIELD	-	ご自身で定義したフィールドに対してクエリをかけられます
select	文字列の配列	指定したフィールドの情報のみ取得する
order	文字列の配列	指定した順番で取得する
skip	数字	何件のコンテンツをスキップするか指定する
depth	数字	画像フィールド・ファイルフィールド・参照フィールドで、取得するデータの階層を指定する
or	配列	いずれかの条件に合致するコンテンツを取得する（複数条件の関係を指定）
and	配列	すべての条件に合致するコンテンツを取得する（複数条件の関係を指定）

フィールドに対して指定可能な演算子

名前	指定形式	説明
なし	-	指定した値に一致するコンテンツを取得する
ne	文字列 / 数字 / 真偽値	指定した値に一致するコンテンツを除外する
match	文字列	指定した値を含むコンテンツを取得する
in	文字列の配列 / 数字の配列	指定した要素のどれかに一致するコンテンツを取得する
nin	文字列の配列 / 数字の配列	指定した要素のどれかに一致するコンテンツを除外する
all	文字列の配列 / 数字の配列	指定した要素のすべてを含むコンテンツを取得する
exists	真偽値	指定したフィールドを持つ（持たない）コンテンツを取得する
gt	文字列 / 数字	指定した値より大きいコンテンツを取得する
gte	文字列 / 数字	指定した値以上のコンテンツを取得する
lt	文字列 / 数字	指定した値未満のコンテンツを取得する
lte	文字列 / 数字	指定した値以下のコンテンツを取得する
fmt	`text`	リッチテキストまたはマークダウンのフィールドに対して、取得形式を（HTMLではなく）テキスト形式にする

getApp: App情報の取得

実行例

const res = await client.getApp({
  appUid: 'YOUR_APP_UID'
})

返却されるレスポンス例

{
  "name": "cool-blog",
  "uid": "cool-blog-123",
  "icon": {
    "type": "emoji",
    "value": "🎾"
  },
  "cover": {
    "type": "image",
    "value": "https://storage.googleapis.com/newt-images/615faa94262844aa189a2f5e/615faa94c374a6532fe4b123/covers/example.jpeg"
  }
},

メソッドで指定可能なパラメータ

名前	必須	説明
appUid	◯	リクエスト対象のApp UID

TypeScriptを利用する場合

事前定義されている型

事前定義されている以下の型を利用することで、型定義を簡単に行なえます。

Content: コンテンツ共通のプロパティが定義されています
Image: 画像フィールドのプロパティが定義されています
File: ファイルフィールドのプロパティが定義されています

Content

コンテンツ共通のプロパティが定義されています。

{
  _id: string
  _sys: {
    createdAt: string
    updatedAt: string
    customOrder: number
    raw: {
      createdAt: string
      updatedAt: string
      firstPublishedAt: string
      publishedAt: string
    }
  }
}

使用例

import type { Content } from 'newt-client-js'

interface Article extends Content {
  title: string
  slug: string
  body: string
}

Image

画像フィールドのプロパティが定義されています。

{
  _id: string
  src: string
  fileName: string
  fileType: string
  fileSize: number
  width: number
  height: number
  title: string
  description: string
  altText: string
  metadata: Record<string, string | number | boolean>
}

使用例

import type { Image } from 'newt-client-js'

interface Author {
  name: string
  profileImage: Image
}

File

ファイルフィールドのプロパティが定義されています。

{
  _id: string
  src: string
  fileName: string
  fileType: string
  fileSize: number
  width: number | null
  height: number | null
  title: string
  description: string
  altText: string
  metadata: Record<string, string | number | boolean>
}

使用例

import type { File } from 'newt-client-js'

interface Event {
  title: string
  datetime: string
  survey: File
}

戻り値の型指定

getContents・getContent・getFirstContent では、ジェネリクスを指定することで、戻り値の型を指定できます。

使用例
例えば getContents の場合、ジェネリクスを指定すると、戻り値の items の型が指定した型の配列となります。
以下の場合、戻り値の items の型は、Article の配列となります。

import type { Article } from '@/types/blog'

const res = await client.getContents<Article>({
  appUid: 'YOUR_APP_UID',
  modelUid: 'YOUR_MODEL_UID',
})

SDK

Table of contents

Content

Image

File