Web pages

Purpose of this API

This API is designed for two main functions: managing drafts and retrieving website content.

The primary entity in this API is a web page, which is linked to a product category. Each product category can be associated with different pages, but only one page per country-language combination and product category is allowed. A page has a layout composed of sections, and these sections can contain variables. The values of these variables are tied to the page and can vary based on the country-language combination.

A draft encompasses all entities, including categories, pages, layouts, sections, variables, and their values. When a draft is published, it updates, removes, or creates new entities, thereby replacing all previous information about these entities.

How to use this API

Object hierarchy

The object hierarchy in this API: Draft → Category → Page → Layout → Section → Variable → Page. In theory, you can create and update any objects in any order you would like, however there are a few caveats:

• Section must be created before Variable that is within this Section. sectionId must be specified, when Variable is created. It cannot be updated later.
• If Layout of a Page is changed, then all Variable values from Sections that are not part of the new Layout are removed. If Sections from old Layout and new Layout overlap, then Variable values are kept.
  • Publishment is not allowed, if not all Variables have values in categories.
• Some Page fields cannot be changed after it was published. This includes associated Category, language and country.
• Layout must be created before Page. layoutId must be specified, when Page is created. Can be updated later.
• Layout cannot be removed, if it is used for any Page.
• Section cannot be removed, if it is used in any Layout.

Status

All Draft API XXX:List and XXX:Retrieve endpoints (apart from Drafts:List) return status of the requested entity. This represents a comparison of drafted entity versus published entity.

Status	Status description
NEW	Entity was created in this draft and has never been published.
MODIFIED	Entity is already published, but will be modified once this draft is published.
REMOVED	Entity is already published, but will be removed once this draft is published.
CURRENT	Entity is already published and will not be changed once this draft is published.

Entity removal

Note that XXX:Delete endpoints do not actually remove an entity from current website content. Instead, it removes the entity from current draft, which means that this draft will no longer modify this entity in any way.

To remove an entity from current website content when draft is published use XXX:Update with “action": “REMOVE” body parameter. This will set the status of REMOVED on that entity. Example:

{
  "action": "REMOVE"
}

Errors and error codes

Error codes in this API documentation do not include error codes for missing or blank variables passed in, when updating or creating entities. Such error codes follow the same structure and apply to all fields that are not nullable or cannot be empty.

Error code structure: web-pages.{action}-{entity}.{field-name}-required and web-pages.{action}-{entity}.{field-name}-blank. For example, web-pages.create-draft.draft-name-required and web-pages.update-layout.layout-name-blank. required means that you cannot use this API without specifying this field. blank means that you can either avoid including this field in the request, assign it to null or populate it with some value, but it cannot be an empty string.

All APIs that use draftId as path parameter can also return web-pages.{action}-{entity}.draft-not-found, which is omitted in APIs' details.

Not included in current version

This version of the API does not include everything that we want to support eventually. List of unsupported features:

• Periods
• Collaboration
• Quick translation
• Version history
• Country support
• Viskan templates
• Import/Export of templates