Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Panel
bgColor#f9f9f1
titleColor#f9f9f1
borderWidth0px
titleBGColor#bc4526
titleOn This Page

Table of Contents




Before you Begin

The following information is applicable to our original import format (called version 1 imports) in order to support new features and increased flexibility Carbon editor supports a new expanded import format (version 2 imports). If you are implementing imports for the first time or as a proof of concept you may wish to continue using version 1 imports for their simplicity, however we recommend that you transition to version 2 imports for production workflows as all new feature development and support will be on version 2 imports. For details on version 2 imports see Version 2 Imports

Please take note of this important information:

  • Updating existing Pages using the Import API will be available in an upcoming release. For now, importing content will result in new Pages being created in the selected Document.
  • The imported content can be:
    • A sole XML file representing one Page, or
    • A .zip file containing one XML file for each Page to be created in Carbon Editor.
  • XML documents define the field types using the "field_type" attribute.
  • XML documents must be saved with UTF-8 as encoding. Otherwise, content might not import correctly.
  • Please ensure your XML is valid against the Liquid State Carbon Editor XSD.


Creating a new Document with the API

Info

Before creating your document, please ensure your content is prepared in a recognisable format.


To create a new Document using the API, you will need your API Token, and the endpoint API URL of the Space.

To retrieve these details, navigate to the Document Category in which you want to create the new Document.

Click the Import Document button.



Your API Token and the endpoint API URL associated with the Space are listed within the Content API section.


To begin your import, make a POST request to the endpoint using the parameters below:


POST Request Headers
Content-Typeapplication/x-www-form-urlencoded
AuthorizationToken API_TOKEN
POST Request Parameters
nameName of the new Document


POST Response Details
Content Typeapplication/json
POST Response Content
UUID

Unique identifier for the newly created Document.

This is a UUID version 4 identifier.

URLThe API URL to access this document.
NameThe name of this document
SlugThe slug used to identify this document in the Carbon Editor interface
ImportsThe API URL used to access the list imports for this document




Importing pages with the API

Using the API, you can import pages in to an existing Document.

Info

You can add pages to a document using the API, regardless of whether the document was originally created with Carbon Editor, or via the API.


You will need your API Token and the endpoint API URL of the specific document you are adding new pages to.

To retrieve your API Token and the endpoint API URL, navigate to the relevant Document.

Click the Import Pages button.

 

Your API Token and the endpoint API URL associated with the document are listed within the Content API section.


To begin your import, make a POST request to the endpoint using the parameters below:


POST Request Headers
Content-Typemultipart/form-data
AuthorizationToken API_TOKEN
POST Request Parameters
import_fileThe .xml or .zip file containing the page or pages you wish to import.


POST Response Details
Content Typeapplication/json
POST Response Content
UUID

Unique identifier for the newly created Document.

This is a UUID version 4 identifier.

URLThe API URL you can access to get details on this import
Status

The current status of the import, progresses from started to complete.

Statuses:

  • started: The import has been received and queued
  • uploading: The import has started, and the import file is being moved to our storage backend
  • in_progress: The import is being processed and pages are being created
  • complete: All the discovered pages have been created.
  • failed: Something went wrong during the import process. Check the failure_message field for more information.
failure_messageIf something is wrong with your import, more details will be provided in this field
total_pagesOnce the import has started, this will reflect the total number of pages to be created.
created_pagesThis is the current number of pages which have been created.
modified_atThe datetime when this import was last updated.




Example Python 3 Script: Create a New Document, Import a Page in to Document

Code Block
languagepy
titleCreating a new document in Python
linenumberstrue
# use the python-requests library: http://docs.python-requests.org
import requests
IMPORT_FILE = './page.xml'
API_TOKEN = 'XXXXXXXXXXX'
ENDPOINT_URL = 'https://editor.liquid-state.com/api/v1/organisations/30e2u269XXXXXX-ed4c-4e11-976c-06c348af546d/spaces/75200d48XXXXXXX-bw58-4484-8e88-60d305ca9e15/documents/'
headers = {
    'Authorization': 'Token {}'.format(API_TOKEN)
}
data = {
    'name': 'My new Document'
}
response = requests.post(ENDPOINT_URL, data=data, headers=headers)
if response.status_code == 200:
    response_obj = response.json()
    new_doc_uuid = response_obj['uuid']
    doc_url = response_obj['url']
    imports_url = response_obj['imports']
    print(new_doc_uuid)
    files = {'import_file': open(IMPORT_FILE, 'rb')}
    response = requests.post(imports_url, files=files, headers=headers)
    if response.status_code == 200:
        print('done')
    else:
    	print("Couldn't upload file")
else:
	print("Couldn't create document")



Info

Your API token is a unique identifier for your user account.

Permissions applied during an API call reflect the permissions associated to the user the API token belongs to.