Editions - /editions/¶

An Edition is a publication of a Product’s documentation. Editions allow products to have multiple versions of documentation published at once, from separate URLs. For example, the ‘latest’ documentation might be published to docs.project.org, but documentation for the tagged ‘v1’ release might be published to docs.project.org/v/v1.

Editions are merely pointers to a Build; an Edition is updated by pointing to a newer Build (see PATCH /editions/(int:id)).

Tracking modes¶

Editions track Builds. This means that when a new Build is uploaded, any Edition for that Product that tracks that kind of Build will be updated. An Edition’s tracking mode is given with the mode field, and can either be set initially (POST /products/(slug)/editions/) or updated on an existing Edition (PATCH /editions/(int:id)).

These are the available tracking modes:

`mode` field	Tracking behavior
git_refs	Git branches and tags
lsst_doc	Latest LSST document version tags
eups_major_release	Latest EUPS major release tags
eups_weekly_release	Latest EUPS weekly release tags
eups_daily_release	Latest EUPS daily release tags

Git reference mode (`git_refs`, default)¶

This mode tracks Builds with a specific Git ref (branch name or tag).

Enable this mode by setting the Edition’s mode field to git_refs. Then set the tracked_refs field with array of Git ref strings that determine the value of git_refs a Build needs to be published as the Edition.

As an example, an Edition has these fields:

{
  "mode": "git_refs",
  "tracked_refs": ["master"]
}

Then a Build with {"git_refs": ["master"]} will be published by the Edition.

LSST document mode (`lsst_doc`)¶

This mode makes the Edition track the Build with the most recent LSST document semantic version tag. LSST document semantic version tags are formatted as v<Major>.<Minor>.

Enable this mode by setting the Edition’s mode field to lsst_doc.

Note that until the first Build with a semantic version tag is published, an Edition with this mode will track the master Git ref.

EUPS major release tag (`eups_major_release`)¶

This mode makes the edition track the Build with the most recent EUPS major release tag.

EUPS major release tags have two forms that are both treated interchangeably:

EUPS tag: vX_Y (as in v15_0).
Git tag: X_Y (as in 15.0).

Enable this mode by setting the Edition’s mode field to eups_major_release.

EUPS weekly release tag (`eups_weekly_release`)¶

This mode makes the edition track the Build with the most recent EUPS weekly release tag.

EUPS weekly release tags have two forms that are both treated interchangeably:

EUPS tag: w_YYYY_WW (as in w_2018_01).
Git tag: w.YYYY.WW (as in w.2018.01).

Enable this mode by setting the Edition’s mode field to eups_weekly_release.

EUPS daily release tag (`eups_daily_release`)¶

This mode makes the edition track the Build with the most recent EUPS daily release tag.

EUPS daily release tags have two forms that are both treated interchangeably:

EUPS tag: d_YYYY_MM_DD (as in d_2018_01_01).
Git tag: d.YYYY.MM.DD (as in d.2018.01.01).

Enable this mode by setting the Edition’s mode field to eups_daily_release.

Methods¶

GET /editions/(int:id) — show a single Edition.
PATCH /editions/(int:id) — update an Edition.
DELETE /editions/(int:id) — deprecate an Edition.

See also:

POST /products/(slug)/editions/ — create a new Edition for a Product.
GET /products/(slug)/editions/ — list all Editions for a Product.

Reference¶

GET /editions/(int: id)¶

Show metadata for an Edition.

Example request

GET /editions/1 HTTP/1.1

Example response

HTTP/1.0 200 OK
Content-Length: 413
Content-Type: application/json
Date: Tue, 01 Mar 2016 18:50:18 GMT
Server: Werkzeug/0.11.3 Python/3.5.0

{
    "build_url": "http://localhost:5000/builds/1",
    "date_created": "2016-03-01T11:50:18.196724Z",
    "date_ended": null,
    "date_rebuilt": "2016-03-01T11:50:18.196706Z",
    "mode": "git_refs",
    "product_url": "http://localhost:5000/products/lsst_apps",
    "published_url": "pipelines.lsst.io",
    "self_url": "http://localhost:5000/editions/1",
    "slug": "latest",
    "surrogate_key": "2a5f38f27e3c46258fd9b0e69afe54fd",
    "title": "Development master",
    "tracked_refs": [
        "master"
    ]
}

Parameters

id – ID of the Edition.

Response JSON Object

build_url (string) – URL of the build entity this Edition uses.
date_created (string) – UTC date time when the edition was created.
date_ended (string) – UTC date time when the edition was deprecated; will be null for editions that are not deprecated.
date_rebuilt (string) – UTC date time when the edition last re-pointed to a different build.
mode (str) – Tracking mode. git_refs: track the Git ref specified by tracked_refs. lsst_doc: track LSST document version tags.
product_url (string) – URL of parent product entity.
published_url (string) – Full URL where this edition is published.
self_url (string) – URL of this Edition entity.
slug (string) – URL-safe name for edition.
surrogate_key (string) – Surrogate key that should be used in the x-amz-meta-surrogate-control header of any the edition’s S3 objects to control Fastly caching.
title (string) – Human-readable name for edition.
tracked_refs (string) – Git ref that this Edition points to. For multi- repository builds, this can be a comma-separated list of refs to use, in order of priority.

Status Codes

200 OK – No errors.
404 Not Found – Edition not found.

PATCH /editions/(int: id)¶

Edit an Edition.

This PATCH method allows you to specify a subset of JSON fields to replace existing fields in the Edition resource. Not all fields in an Edition are editable via the API. See the allowed JSON fields below.

Use DELETE /editions/(int:id) to deprecate an edition.

The full resource record is returned.

Authorization

User must be authenticated and have admin_edition permissions.

Example request

PATCH /editions/1 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic ZXlKcFlYUWlPakUwTlRZM056SXpORGdzSW1WNGNDSTZNVFEx...
Connection: keep-alive
Content-Length: 31
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/0.9.3

{
    "title": "Development master"
}

Example response

HTTP/1.0 200 OK
Content-Length: 413
Content-Type: application/json
Date: Tue, 01 Mar 2016 17:21:29 GMT
Server: Werkzeug/0.11.3 Python/3.5.0

{
    "build_url": "http://localhost:5000/builds/2",
    "date_created": "2016-03-01T10:21:29.017615Z",
    "date_ended": null,
    "date_rebuilt": "2016-03-01T10:21:29.590839Z",
    "mode": "git_refs",
    "product_url": "http://localhost:5000/products/lsst_apps",
    "published_url": "pipelines.lsst.io",
    "self_url": "http://localhost:5000/editions/1",
    "slug": "latest",
    "surrogate_key": "2a5f38f27e3c46258fd9b0e69afe54fd",
    "title": "Development master",
    "tracked_refs": [
        "master"
    ]
}

Request Headers

Authorization – Include the token in a username field with a blank password; <token>:.

Parameters

id – ID of the Edition.

Request JSON Object

build_url (string) – URL of the build entity this Edition uses (optional). Effectively this ‘rebuilds’ the edition.
title (string) – Human-readable name for edition (optional).
slug (string) – URL-safe name for edition (optinal). Changing the slug dynamically updates the published_url.
mode (str) – Tracking mode. git_refs: track the Git ref specified by tracked_refs. lsst_doc: track LSST document version tags.
tracked_refs (array) – Git ref(s) that this Edition points to. For multi-package documentation builds this is a list of Git refs that are checked out, in order of priority, for each component repository (optional).
pending_rebuild (bool) – Semaphore indicating if a rebuild for the edition is currently queued (optional). This should only be set manually if the rebuild_edition task failed.

Response JSON Object

build_url (string) – URL of the build entity this Edition uses.
date_created (string) – UTC date time when the edition was created.
date_ended (string) – UTC date time when the edition was deprecated; will be null for editions that are not deprecated.
date_rebuilt (string) – UTC date time when the edition last re-pointed to a different build.
mode (str) – Tracking mode. git_refs: track the Git ref specified by tracked_refs. lsst_doc: track LSST document version tags.
product_url (string) – URL of parent product entity.
published_url (string) – Full URL where this edition is published.
self_url (string) – URL of this Edition entity.
slug (string) – URL-safe name for edition.
surrogate_key (string) – Surrogate key that should be used in the x-amz-meta-surrogate-control header of any the edition’s S3 objects to control Fastly caching.
title (string) – Human-readable name for edition.
tracked_refs (string) – Git ref that this Edition points to, for use with the git_refs tricking mode. For multi-repository products, this can be a comma-separated list of refs to use, in order of priority.

Status Codes

200 OK – No errors.
404 Not Found – Edition resource not found.

DELETE /editions/(int: id)¶

Deprecate an Edition of a Product.

When an Edition is deprecated, the current time is added to the Edition’s date_ended field. Any Edition record with a non-null date_ended field will be garbage-collected by LTD Keeper (the deletion does not occur immediately upon API request).

Authorization

User must be authenticated and have admin_edition permissions.

Example request

DELETE /editions/1 HTTP/1.1
Authorization: Basic ZXlKcFlYUWlPakUwTlRZM056SXpORGdzSW1WNGNDSTZNVFEx...
Connection: keep-alive
Content-Length: 0
Host: localhost:5000
User-Agent: HTTPie/0.9.3

Example response

HTTP/1.0 200 OK
Content-Length: 2
Content-Type: application/json
Date: Tue, 01 Mar 2016 17:21:30 GMT
Server: Werkzeug/0.11.3 Python/3.5.0

{}

Request Headers

Authorization – Include the token in a username field with a blank password; <token>:.

Parameters

id – Edition id.

Status Codes

200 OK – No errors.
404 Not Found – Edition not found.

Editions - /editions/¶

Tracking modes¶

Git reference mode (git_refs, default)¶

LSST document mode (lsst_doc)¶

EUPS major release tag (eups_major_release)¶

EUPS weekly release tag (eups_weekly_release)¶

EUPS daily release tag (eups_daily_release)¶

Methods¶

Reference¶

Git reference mode (`git_refs`, default)¶

LSST document mode (`lsst_doc`)¶

EUPS major release tag (`eups_major_release`)¶

EUPS weekly release tag (`eups_weekly_release`)¶

EUPS daily release tag (`eups_daily_release`)¶