API Format

Live Editor’s RESTful API allows you to read and write data to and from your Live Editor-hosted website. Outlined here are concepts to become familiar with in order to work with our API in your own applications.

Based on JSON API 1.0

JSON API is a “specification for building APIs in JSON.” We chose this format to provide consistency for our API’s JSON document formats, URLs, and more. The specification is also well-documented by a community with extensive expertise in designing APIs.

Following are the most notable conventions adopted into our API.

Content-Type headers

The client must send all requests to the Live Editor API with a Content-Type header of application/vnd.api+json.

Any responses from the Live Editor API containing JSON content in the response body will also include a Content-Type header of application/vnd.api+json.

URLs and resource endpoints

Access to the API is based on your website’s admin subdomain and which Live Editor region it’s hosted on.

If your website’s subdomain is coffee and is hosted in the North America region, for example, the URL for accesing the API is as follows:

https://coffee.api.liveeditorapp.com/

All resource endpoints are in “dasherized” format. Their names are plural.

For example, to reach the External URLs service, you would use the following URL:

https://coffee.api.liveeditorapp.com/external-urls

Versioning

By default, all requests receive version 1 of the API. To maintain the stability of your API client, it is recommended that you explicitly request this version via an X-API-Version header:

X-API-Version: 1

One day, there will probably be a version 2. You don’t want to be surprised on that day when your API client stops working because we updated the API and you receive the new default.

Data Schema

Each record represented in the JSON object returned will contain id, type, and possibly an attributes object.

All ids will consist of a UUID (version 4). All ids will be generated by the Live Editor API; client-generated ids will be ignored.

All multi-word attribute names are “dasherized” (e.g., first-name).

There are a couple different scenarios for how data will be structured: reading single records and reading a list of records.

Reading a single record

Reading a single record outputs a data object containing the record.

Example:

      {
        "data": {
          "type": "users",
          "id": "26753e6f-d93c-48ba-bc48-8100d0330a0f",
          "attributes": {
            "first-name": "Steve",
            "last-name": "Scuba",
            "email": "scubasteve@example.com"
          }
        }
      }

Reading a list of records

Reading multiple records outputs a data array containing the objects representing each record.

Example:

      {
        "data": [
          {
            "type": "users",
            "id": "dfb6958a-1268-493d-9770-8911aff51637",
            "attributes": {
              "first-name": "Steve",
              "last-name": "Scuba",
              "email": "scubasteve@example.com"
            }
          },
          {
            "type": "users",
            "id": "db69c524-5416-4212-9f69-245ba09e763f",
            "attributes": {
              "first-name": "Happy",
              "last-name": "Gilmore",
              "email": "happy@example.com"
            }
          }
        ]
      }