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']}