Builds - /builds/

In LTD Keeper, a Build is created every time a Sphinx repository is compiled and uploaded to S3. LTD Keeper doesn’t touch objects in S3 directly; LTD Mason uploads documentation sites to S3 and then registers the build with LTD Keeper.

New builds added using the POST /products/(slug)/builds/ method. The other methods listed on this page allow you to list and maintain Builds (such as showing or deprecating them).

Methods

See also:

Reference

GET /builds/(int: id)

Show metadata for a single build.

Example request

GET /builds/1 HTTP/1.1

Example response

HTTP/1.0 200 OK
Content-Length: 367
Content-Type: application/json
Date: Tue, 01 Mar 2016 17:21:28 GMT
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": true
}
Parameters

  • id – ID of the Build.

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).

  • slug (string) – slug of build; URL-safe slug.

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

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

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

  • 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.

Status Codes
PATCH /builds/(int: id)

Mark a build as uploaded.

This method should be called when the documentation has been successfully uploaded to the S3 bucket, setting the ‘uploaded’ field to True.

Authorization

User must be authenticated and have upload_build permissions.

Example request

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

{
    "uploaded": true
}

Example response

HTTP/1.0 200 OK
Content-Length: 2
Content-Type: application/json
Date: Tue, 01 Mar 2016 17:21:28 GMT
Location: http://localhost:5000/builds/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

  • id – ID of the build.

Request JSON Object

  • uploaded (bool) – True if the built documentation has been uploaded to the S3 bucket.

Response Headers

  • Location – URL of the created build.

Status Codes
DELETE /builds/(int: id)

Mark a build as deprecated.

Authorization

User must be authenticated and have deprecate_build permissions.

Example request

DELETE /builds/1 HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
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:29 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 – ID of the build.

Status Codes