Products - /products

The /products/ API allows you to list Products, create new Products, and update Products (including adding new Builds and Editions).

In LTD Keeper, a Product is the root entity associated with a documentation project. Generally, a single Sphinx documentation repository maps to a Product. LTD Keeper can host documentation for several products.

The actual documentation associated with a Product is manifested by Builds. In turn, Builds are the source of Editions, which are published versions of the Product’s documentation.

Method summary

• GET /products/ — list all documentation products.

• GET /products/(slug) — show a single product.

• POST /products/ — create a new product.

• PATCH /products/(slug) — update a product’s metadata.

• POST /products/(slug)/builds/ — create a new build for a product.

• GET /products/(slug)/builds/ — list all builds for a product.

• POST /products/(slug)/editions/ — create a new edition for a product.

• GET /products/(slug)/editions/ — list all editions for a product.

• POST /products/(slug)/dashboard — manually rebuild the dashboards for a product.

See also:

• /builds/

• /editions/

Reference

GET /products/

List all documentation products (anonymous access allowed).

Example request

GET /products/ HTTP/1.1

Example response

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

{
    "products": [
        "http://localhost:5000/products/lsst_apps",
        "http://localhost:5000/products/qserv_distrib"
    ]
}

Response JSON Object

• products (array) – List of product URLs.

Status Codes

• 200 OK – No error.

GET /products/(slug)

Get the record of a single documentation product (anonymous access allowed).

Example request

GET /products/pipelines HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Basic ZXlKaGJHY2lPaUpJVXpJMU5pSXNJbVY0Y0NJNk1UUTJNVEV3...
Connection: keep-alive
Host: localhost:5000
User-Agent: HTTPie/0.9.3

Example response

HTTP/1.0 200 OK
Content-Length: 385
Content-Type: application/json
Date: Tue, 19 Apr 2016 21:17:52 GMT
Server: Werkzeug/0.11.3 Python/3.5.0

{
    "bucket_name": "an-s3-bucket",
    "doc_repo": "https://github.com/lsst/pipelines_docs.git",
    "domain": "pipelines.lsst.io",
    "fastly_domain": "pipelines.lsst.io.global.ssl.fastly.net",
    "root_domain": "lsst.io",
    "root_fastly_domain": "global.ssl.fastly.net",
    "self_url": "http://localhost:5000/products/pipelines",
    "slug": "pipelines",
    "surrogate_key": "2a5f38f27e3c46258fd9b0e69afe54fd",
    "title": "LSST Science Pipelines"
}

Parameters

• slug – Identifier for this product.

Response JSON Object

• bucket_name (string) – Name of the S3 bucket hosting builds.

• doc_repo (string) – URL of the Git documentation repo (i.e., on GitHub).

• domain (string) – Full domain where this product’s documentation is served from this LSST the Docs installation is served from. (e.g., pipelines.lsst.io).

• fastly_domain (string) – Full domain where Fastly serves content for this product. Note that domain is CNAME’d to fastly_domain.

• root_domain (string) – Root domain name where documentation for this LSST the Docs installation is served from. (e.g., lsst.io).

• root_fastly_domain (string) – Root domain name for Fastly CDN used by this LSST the Docs installation.

• published_url (string) – Full URL where this product is published to the reader.

• self_url (string) – URL of this Product resource.

• slug (string) – URL/path-safe identifier for this product.

• surrogate_key (string) – Surrogate key that should be used in the x-amz-meta-surrogate-control header of any product-level dashboards to control Fastly caching.

• title (string) – Human-readable product title.

Status Codes

• 200 OK – No error.

• 404 Not Found – Product not found.

POST /products/

Create a new documentation product.

Every new product also includes a default edition (slug is ‘main’). This main edition tracks the master branch by default. Fastly is configured to show this main edition at the product’s root URL rather than in the /v/ directory.

Authorization

User must be authenticated and have admin_product permissions.

Example request

POST /products/ HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic ZXlKaGJHY2lPaUpJVXpJMU5pSXNJbVY0Y0NJNk1UUTJNVEV3...
Connection: keep-alive
Content-Length: 218
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/0.9.3

{
    "bucket_name": "an-s3-bucket",
    "doc_repo": "https://github.com/lsst/pipelines_docs.git",
    "root_domain": "lsst.io",
    "root_fastly_domain": "global.ssl.fastly.net",
    "slug": "pipelines",
    "surrogate_key": "2a5f38f27e3c46258fd9b0e69afe54fd",
    "title": "LSST Science Pipelines"
}

Example response

HTTP/1.0 201 CREATED
Content-Length: 2
Content-Type: application/json
Date: Tue, 19 Apr 2016 21:17:52 GMT
Location: http://localhost:5000/products/pipelines
Server: Werkzeug/0.11.3 Python/3.5.0

{}

Request Headers

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

Request JSON Object

• bucket_name (string) – Name of the S3 bucket hosting builds.

• doc_repo (string) – URL of the Git documentation repo (i.e., on GitHub).

• main_mode (str) – Tracking mode for the main (default) edition. git_refs: track the master branch. lsst_doc: track LSST document version tags.

• root_domain (string) – Root domain name where documentation for this LSST the Docs installation is served from. (e.g., lsst.io).

• root_fastly_domain (string) – Root domain name for Fastly CDN used by this LSST the Docs installation.

• self_url (string) – URL of this Product resource.

• slug (string) – URL/path-safe identifier for this product. The slug is validated against the regular expression ^[a-z]([-]*[a-z0-9])*$.

• title (string) – Human-readable product title.

Response Headers

• Location – URL of the created product.

Status Codes

• 201 Created – No error.

PATCH /products/(slug)

Update a product.

Note that not all fields can be updated with this method (currently). See below for updateable fields. Contact the operator to update the slug, bucket name, or Fastly domain.

Authorization

User must be authenticated and have admin_product permissions.

Example request

PATCH /products/qserv HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic ZXlKaGJHY2lPaUpJVXpJMU5pSXNJbVY0Y0NJNk1UUTJNVEV3...
Connection: keep-alive
Content-Length: 30
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/0.9.3

{
    "title": "Qserv Data Access"
}

Example response

HTTP/1.0 200 OK
Content-Length: 2
Content-Type: application/json
Date: Tue, 19 Apr 2016 21:17:53 GMT
Location: http://localhost:5000/products/qserv
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

• slug – Product slug.

Request JSON Object

• doc_repo (string) – URL of the Git documentation repo (i.e., on GitHub) (optional).

• title (string) – Human-readable product title (optional).

Response Headers

• Location – URL of the created product.

Status Codes

• 200 OK – No error.

• 404 Not Found – Product not found.

POST /products/(slug)/builds/

Add a new build for a product.

This method only adds a record for the build and specifies where the build should be uploaded. The client is reponsible for uploading the build. Once the documentation is uploaded, send PATCH /builds/(int:id) to set the ‘uploaded’ field to True.

If the user also has admin_edition permissions, this method will also create an edition that tracks this build’s git_refs (if they are not already tracked). The slug and title of this edition are automatically derived from the build’s git_refs.

Authorization

User must be authenticated and have upload_build permissions.

Example request

POST /products/lsst_apps/builds/ HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic ZXlKcFlYUWlPakUwTlRZM056SXpORGdzSW1WNGNDSTZNVFEx...
Connection: keep-alive
Content-Length: 74
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/0.9.3

{
    "git_refs": [
        "master"
    ],
    "github_requester": "jonathansick",
    "slug": "b1"
}

Example response

HTTP/1.0 201 CREATED
Content-Length: 368
Content-Type: application/json
Date: Tue, 01 Mar 2016 17:21:27 GMT
Location: http://localhost:5000/builds/1
Server: Werkzeug/0.11.3 Python/3.5.0

{
    "bucket_name": "an-s3-bucket",
    "bucket_root_dir": "lsst_apps/builds/b1",
    "date_created": "2016-03-01T10:21:27.583795Z",
    "date_ended": null,
    "git_refs": [
        "master"
    ],
    "github_requester": "jonathansick",
    "product_url": "http://localhost:5000/products/lsst_apps",
    "self_url": "http://localhost:5000/builds/1",
    "slug": "b1",
    "surrogate_key": "d290d35e579141e889e954a0b1f8b611",
    "uploaded": false
}

Request Headers

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

Parameters

• slug – Product slug.

Request JSON Object

• git_refs (array) – Git ref array that describes the version of the documentation being built. Typically this array will be a single string, e.g. ['master'] but may be a list of several refs for multi-package builds with ltd-mason.

• github_requester – Optional GitHub username handle of person who triggered the build.

• slug (string) – Optional URL-safe slug for the build. If a slug is not specified, then one will automatically be specified.

Response JSON Object

• bucket_name (string) – Name of the S3 bucket hosting the built documentation.

• bucket_root_dir (string) – Directory (path prefix) in the S3 bucket where this documentation build is located.

• date_created (string) – UTC date time when the build was created.

• date_ended (string) – UTC date time when the build was deprecated; will be null for builds that are not deprecated.

• git_refs (array) – Git ref array that describes the version of the documentation being built. Typically this array will be a single string, e.g. ['master'] but may be a list of several refs for multi-package builds with ltd-mason.

• github_requester (string) – GitHub username handle of person who triggered the build (null is not available).

• product_url (string) – URL of parent product entity.

• self_url (string) – URL of this build entity.

• slug (string) – Slug of build; URL-safe slug. Will be unique to the Product.

• surrogate_key (string) – The surrogate key attached to the headers of all files on S3 belonging to this build. This allows LTD Keeper to notify Fastly when an Edition is being re-pointed to a new build. The client is responsible for uploading files with this value as the x-amz-meta-surrogate-key value.

• uploaded (bool) – True if the built documentation has been uploaded to the S3 bucket. Use PATCH /builds/(int:id) to set this to True.

Response Headers

• Location – URL of the created build.

Status Codes

• 201 Created – No error.

• 404 Not Found – Product not found.

GET /products/(slug)/builds/

List all builds for a product.

Example request

GET /products/lsst_apps/builds/ HTTP/1.1

Example response

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

{
    "builds": [
        "http://localhost:5000/builds/1",
        "http://localhost:5000/builds/2"
    ]
}

Parameters

• slug – Slug of the Product.

Response JSON Object

• builds (array) – List of URLs of Build entities for this product.

Status Codes

• 200 OK – No error.

• 404 Not Found – Product not found.

POST /products/(slug)/editions/

Create a new Edition for a Product.

Authorization

User must be authenticated and have admin_edition permissions.

Example request

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

{
    "build_url": "http://localhost:5000/builds/1",
    "slug": "latest",
    "title": "Latest",
    "mode:": "git_refs",
    "tracked_refs": [
        "master"
    ]
}

Example response

HTTP/1.0 201 CREATED
Content-Length: 2
Content-Type: application/json
Date: Tue, 01 Mar 2016 17:21:29 GMT
Location: http://localhost:5000/editions/1
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

• slug – Product slug.

Request JSON Object

• build_url (string) – URL of the build entity this Edition uses.

• slug (string) – URL-safe name for edition. Don’t include this field when using autoincrement: true.

• title (string) – Human-readable name for edition.

• 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 describe the version of the Product that this this Edition is intended to point to when using the git_refs tracking mode.

• autoincrement (bool) – Instead of providing a slug, the server automatically assigns an integer slug that is one larger than existing slug integers. Starts from 1.

Response Headers

• Location – URL of the created Edition resource.

Status Codes

• 201 Created – No errors.

• 404 Not Found – Product not found.

GET /products/(slug)/editions/

List all editions published for a Product.

Example request

GET /products/lsst_apps/editions/ HTTP/1.1

Example response

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

{
    "editions": [
        "http://localhost:5000/editions/1"
    ]
}

Parameters

• slug – Slug of the Product.

Response JSON Object

• editions (array) – List of URLs of Edition entities for this Product.

Status Codes

• 200 OK – No errors.

• 404 Not Found – Product not found.

POST /products/(slug)/dashboard

Rebuild the LTD Dasher dashboard manually for a single product.

Note that the dashboard is built asynchronously.

Authorization

User must be authenticated and have admin_product permissions.

Status Codes

• 202 Accepted – Dashboard rebuild trigger sent.

See also

• POST /dashboards