概要

リクエスト

すべてのAPIのURLは以下の形式で始まり、以降にAPIごとに異なるパスが続きます。

以下は、URLの例です。

すべてのAPIのパラメータは、参照系APIはGETで、更新系APIはPOSTで渡します。
POSTの場合のリクエストボディは、application/x-www-form-urlencoded または multipart/ form-dataの形式で渡します。
これは、一般的なWebページのフォーム送信で使用される形式と同じです。
ただし、ファイルのアップロードを行う一部のAPIでは、multipart/form-dataの形式のみに対応しています。
パラメータの文字コードは、UTF8に対応しています。

※リクエスト頻度についての注意事項
1分間に60回を超えるAPIコールには自動制限機能(Rate Limit機能)がかかり、次の1分になると制限が解除される仕様となりますのでご注意ください。

レスポンス

すべてのAPIは、200番のステータスコードと一緒にレスポンスボディを返します。
レスポンスボディはJSONオブシェクトで返されます。
トップレベルのokプロパティは、処理が成功したか失敗したかを表わします(trueが成功、falseが失敗)。

成功時のレスポンスの例は、以下のとおりです。返すデータがあれば、okと一緒に返します。

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
    "ok": true,
    "unit": {
        "id": "0123456",
        "name": "ノアドット新聞",
        ...
    }
}

失敗時のレスポンスの例は、以下のとおりです。errorプロパティでエラーコードを返します。
また、エラーについて補足情報がある場合は、error_detailプロパティも返す場合があります。

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
    "ok": false,
    "error": "invalid_body",
    "error_detail": “markdown syntax error, near ’[[image](2345678’ on line 10",
}

共通エラー

すべてのAPIで共通のエラーコードは、以下のとおりです。
下記以外のエラーコードは、各APIの 詳細を参照してください。

認証

APIを使用するには、以下の手順で認証を行う必要があります。

1. nor.cmsでアクセストークンを発行

nor.が提供する管理ツール(nor.cms)にログインして、アクセストークンを発行します。
アクセストークン内部には、そのアクセストークンで操作できるユニットの情報を含んでいます。
アクセストークンの発行は最初に一度だけ行います。

2. アクセストークンを使用して目的のAPIを実行

取得したアクセストークンをAuthorizationヘッダーに付与して、目的のAPIを実行します。
以下はリクエストの例です。

GET /v1.0/contentsholder/posts.info HTTP/1.1
Host: api.nordot.jp
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
...

認証に成功すると、APIが正常に実行されてレスポンスが返さます。
アクセストークンが渡されなかった場合やアクセストークンが不正な場合は、エラーレスポンスが返されます。
以下は、エラーレスポンスの例です。エラーの詳細については、共通エラーの項目を参照してください。

{
    "ok": false,
    "error": "invalid_access_token"
}

以下は、アクセストークンに関する注意事項です。

アクセストークンは、漏洩するとAPIを自由に実行されてしまうため大切に管理してください。

アクセストークンの漏洩を防止するため、必ずSSL(https)を使用してAPIを実行してください。

万が一アクセストークンが漏洩してしまった場合には、nor.cmsで新しいアクセストークンを再発行できます。古いアクセストークンは使用できなくなります。

日時データとタイムゾーン

RFC 3339は、コンピュータにおける日時の表現方法について定めた国際規格です。
協定世界時 (UTC)の場合、サフィックスとして"+00:00"を付加します。
地方時の場合は、協定世界時との 時差を"+09:00"のように付加します。

APIのリクエストパラメータで日時データを送信する場合は、任意のタイムゾーンを使用できます。
例えば、以下の2つはタイムゾーンは異なっても同じ日時を表しているため、どちらをパラメータで送信した場合も、
APIでは同じ日時と判断して処理が行われます。

APIのレスポンスで返される日時データは、すべて協定世界時のタイムゾーンで返されます。
そのため、地方時で使用したい場合はAPI利用者側で地方時に変換する必要があります。
以下は、レスポンスで返されたcreated_atとupdated_atの値の例です。

{
    "created_at": "2015-11-10T20:09:31+00:00",
    "updated_at": "2015-12-25T18:58:10+00:00",
    ...
}