addadd-thickarrow-downaxebreadcrumb dividercameracc-compulsarychatclosecontactdata-usersdebugdevelopersdismissdocumentserrorglossaryinfolinkpublisherssearchselect-dropdownsuccesstableswarning

Developers

APIs to manage your site, query data and build new products and services.

  1. Home
  2. Developers
  3. Publisher Admin API
  4. Publishing API

Publishing API

The Publishing API allows for draft versions of versioned objects - i.e. documents, layers and tables - to be scheduled for publishing together.

Publish tasks

GET /publish/
List publish tasks

Returns a list of publish tasks.

Parameters

  • state: string (optional). Returns Publish Tasks in the specified state. Valid Publish states are: waiting-for-items, waiting-for-time, waiting-for-approval, publishing, cancelled, cancelled-due-to-error, errored, completed.
  • reference: string (optional). Returns Publish Tasks with the specified reference.

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": 123,
        "url": "https://{domain}/services/api/v1/publish/123/",
        "state": "waiting-for-items",
        "created_at": "2015-08-19T00:00:01T",
        "items": [
            "https://{domain}/services/api/v1/layers/4/versions/44/",
            "https://{domain}/services/api/v1/tables/5/versions/55/",
            "https://{domain}/services/api/v1/layers/6/versions/66/",
        ],
        "publish_strategy": "together",
        "error_strategy": "abort",
        "reference": "1234abcd",
        "publish_at": "2015-08-20T12:00:00Z"
    }
]
POST /publish/
Create a new publish task

Create a publish job for a number of draft layers/tables/documents. The items will be published when all the drafts are ready:

items: List of urls of draft versions to publish

publish_strategy: One of: "manual", "together". Default = "together"

  • The together strategy will publish all items once they have all finished importing/updating.
  • The manual strategy will publish all items once they have all finished importing/updating and have been approved by posting to /publish/{id}/approve/.
  • error_strategy: One of: "abort", "ignore". Default = "abort"
  • The abort strategy will leave all items in their draft state if one of them encounters an error during importing/updating.
  • The ignore strategy will publish any successful items and leave any errored items in their draft state
reference: Optional user-defined reference.

Request

Headers

Content-Type: application/json

Body

{
    "items": [
        "https://{domain}/services/api/v1/tables/5/versions/456/",
        "https://{domain}/services/api/v1/layers/6/versions/789/",
    ],
    "publish_strategy": "together",
    "error_strategy": "abort",
    "reference": "1234abcd"
}

Response 201

Headers

Location: https://{domain}/services/api/v1/publish/456/

Body

# this change didn't require a reimport. The publish has taken place.

Response 202

Headers

Location: https://{domain}/services/api/v1/publish/456/

Body

# reimport required. The publish task has been created but is not yet finished.

Response 400

Headers

Content-Type: application/json

Body

{"error": "One or more of the drafts was an invalid version."}

Response 409

Headers

Content-Type: application/json

Body

{"error": "One or more of the drafts was already published."}

Publish Detail

Get the current state of a publish task.

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 123,
    "url": "https://{domain}/services/api/v1/publish/123/",
    "state": "waiting-for-items",
    "created_at": "2015-08-19T00:00:01T",
    "items": [
        "https://{domain}/services/api/v1/layers/4/versions/44/",
        "https://{domain}/services/api/v1/tables/5/versions/55/",
        "https://{domain}/services/api/v1/layers/6/versions/66/",
    ],
    "publish_strategy": "together",
    "error_strategy": "abort",
    "reference": "1234abcd",
    "publish_at": "2015-08-20T12:00:00Z"
}
DELETE /publish/{id}/
Cancel publish task

Cancel a pending publish task.

Response 202

Body

# update cancelled

Response 409

Headers

Content-Type: application/json

Body

{"not-cancelable": ['This publish is not cancelable']}

Approve publish

POST /publish/{id}/approve/
Approve a manual publish task

Approves a task with a manual publish strategy that is in the waiting-for-approval state.

Response 202

Body

# Approval accepted. Publishing will begin shortly.

Response 409

Headers

Content-Type: application/json

Body

{"not-approvable": ['This publish can not be approved']}