Documentation Overview

Welcome to the “nor.” public API documentation. This documentation is the official reference for the services offered by the nor. public APIs. The APIs use standard HTTP response codes to indicate API errors and returns JSON objects for API responses.

Requests

Every API request made in this documentation has the base URL shown below:

https://api.nordot.jp/v1.0/

All API requests should be made with this base URL, followed by the corresponding URL path. For example:

https://api.nordot.jp/v1.0/contentsholder/units.info

Notes about included HTTP verbs:

GET: The GET method retrieves a resource or a list of resources (data retrieval).

POST: The POST method creates or updates a resource (data creation). The POST request body requires the application/x-www-form-urlencoded or multipart/form-data format. This is similar to the submit form used in common web pages. However, certain APIs that perform a file upload operation will require the multipart/form-data format. Parameter text supports UTF-8 encoding.

Responses

A successful API call returns the 200-OK status code along with the response body, which is a JSON object. The top-level “ok” property indicates the status of the operation (true: success, false: failed).

This is an example of asuccessful response. The response includes additional resource information if available.

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

{
    "ok": true,
    "unit": {
        "id": "0123456",
        "name": "The Nordot Post",
        ...
    }
}

This is an example of a standard failed response. The "error" property returns the error code and the "error_detail" property returns additional information about the error, if available.

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",
}

Common Errors

The table below describes common API error codes encountered by users. We encourage you to review the API error section of the document for more information about supplementary error codes.

Error Code Description
no_access_token The access token required for authentication is not specified
invalid_access_token The access token supplied is invalid. For example, an invalid token format, the token has already been deleted or has no access permission to the API.
server_error An error occurs in the nor. API server or in the nor. system
service_unavailable The service is temporarily unavailable due to overload or maintenance

Authentication

Authenticate your account using an access token in your API requests. Keep your access token in a private, safe location and do not store them in public or unrestricted domains.

To obtain an access token and execute API requests, follow the steps outlined below:

1. Obtain the access token

The access token contains important information about which Media Units it controls (authorized access).
You can get your access token via the nor. content management system (also referred to as the CMS).
You will need to log in to the CMS to get your access token. Once obtained, the access token has no expiry dates and can be reissued.

2. Execute API calls using the access token

Execute the API call by including the access token in the Authorization header.
This is a request example:

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

If the authentication and API request is successful, a successful status response is returned. An error is returned for a missing or invalid access token. Please refer to the “Common Errors” section for more details about returned errors.

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

Some important notes:

Keep your access tokens in a safe and secure location.

All API requests should be made over HTTPS.

API requests made without access tokens or made over basic HTTP will fail.

If your access token is compromised, you can obtain a new access token from the CMS. This invalidates the previous token.

Dates and Times, Time zones

The date and time related data handled in parameters and responses are in ISO 8601 format.

YYYY-MM-DDTHH:MM:SS+hh:mm

ISO 8601 is an international standard format specifying representation of date and time related data. If the time is in Coordinated Universal Time(UTC), "+00:00" will be added as a suffix. For other time zones, the offset from the UTC time zone will be appended with a zone designator such as "+09:00".

You can use your preferred time zone when you send an API request argument. For example, the date and time formats below indicate the same date and time, albeit each format has a different time zone. In each scenario, the API will recognize and accept the date-time data.

2015-10-10T04:50:40+00:00 # 4:50:40, October 10, 2015 in UTC
2015-10-10T13:50:40+09:00 # 13:50:40, October 10, 2015 in JST

All timestamps returned in the API responses will use the UTC time zone. Therefore, API users will need to convert the date-time value to local time if necessary.

This is an example of a response with “created_at” and “updated_at” properties and values:

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

Notes on the API Request Rate

Currently, there are no limits to the number of API requests a user can make. However, excessive requests might have a negative impact on server resources.

Please add reasonable time intervals in between each request i.e.one second (1 sec.), to avoid negative consequences.

If the number of API requests or request rate exceeds the projected server capacity, we reserve the right to limit or truncate API requests rate without prior notice to the API user or consumer.

An automated time-based restrict (Rate Limit) function will be introduced in a subsequent version of the API(s).