Back to top

Deploynaut API

This API conforms to the JSON API specifications.

Using the API

In order to use the API, you will need to acquire an API token by going to the profile section of the Dashboard (at “naut/profile”), and clicking the “API token” button.

In order to authenticate you must use HTTP Basic Authentication with your email as a username and API token as a password.

Caution: protect the “Authorization” header just as you would any password, i.e. do not send it over email or submit it via Service Desk/Helpdesk. The secret token is easily recoverable from that header.

Example request

Example request
GET/naut/meta

Example URI

GET /naut/meta
Request
HideShow
Headers
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
X-Api-Version: 2.0
Authorization: Basic am9lQGV4YW1wbGUuY29tOnRlc3Q=
Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "meta": {
    "whoami": "joe@example.com",
    "now": "2017-05-09 11:57:00"
  }
}

Example error

Example error
GET/naut/not-found-example

Example URI

GET /naut/not-found-example
Response  404
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "errors": [
    {
      "status": 404,
      "title": "Action 'not-found-example' isn't available on class DNRoot."
    }
  ]
}

Major releases

2.0

Backwards incompatibilities

  • Changed type of the status field in the errors structure to string (was numeric).

  • Changed type of the ID field of the “deployments” resource to string (was numeric).

  • Removed *_ago and *_nice datetime fields on the “deployments” resource, replaced with *_unix.

1.0

Initial release.

Stacks

Stacks collection

List all
GET/naut/projects

Will return a list of all stacks that you have the authority to view, with relevant datapoints.

Example URI

GET /naut/projects
Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": [
    {
      "type": "stacks",
      "id": "stack1",
      "attributes": {
        "name": "stack1",
        "title": "stack1",
        "created": "2014-07-02 00:00:00",
        "created_unix": 1388534400
      },
      "relationships": {
        "environments": {
          "data": [
            {
              "type": "environments",
              "id": "Production",
              "links": {
                "self": "http://example.com/naut/project/stack1/environment/Production"
              }
            },
            {
              "type": "environments",
              "id": "UAT",
              "links": {
                "self": "http://example.com/naut/project/stack1/environment/UAT"
              }
            }
          ]
        }
      },
      "links": {
        "self": "http://example.com/naut/project/stack1"
      }
    }
  ]
}

Stack

View
GET/naut/project/{project_id}

Example URI

GET /naut/project/stack1
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "stacks",
    "id": 1,
    "attributes": {
      "name": "stack1",
      "title": "stack1",
      "created": "2014-07-02 00:00:00"
    },
    "relationships": {
      "environments": {
        "data": [
          {
            "type": "environments",
            "id": "Production",
            "links": {
              "self": "http://example.com/naut/project/stack1/environment/Production"
            }
          },
          {
            "type": "environments",
            "id": "UAT",
            "links": {
              "self": "http://example.com/naut/project/stack1/environment/UAT"
            }
          }
        ]
      }
    },
    "links": {
      "self": "http://example.com/naut/project/stack1"
    }
  }
}

Environments

Environment

View
GET/naut/project/{project_id}/environment/{environment_id}

Example URI

GET /naut/project/stack1/environment/Production
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "environments",
    "id": "prod",
    "attributes": {
      "name": "Production",
      "build_sha": "0cf36448607fe900ecbe48c280440be2d7b9385a",
      "maintenance_day": "Saturday",
      "maintenance_time": "03:00:00",
      "maintenance_duration": "02:00:00",
      "maintenance_tz": "Pacific/Auckland",
      "usage": "Production"
    },
    "relationships": {
      "stack": {
        "data": {
          "type": "stacks",
          "id": "stack1",
          "links": {
            "self": "http://example.com/naut/project/stack1"
          }
        }
      }
    }
  }
}

Git fetches

Git fetches collection

Create
POST/naut/project/{project_id}/git/fetches

Queues a new “fetch” on the repository associated with this project.

Example URI

POST /naut/project/stack1/git/fetches
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

Response  202
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "fetches",
    "id": 1,
    "attributes": {
      "status": "n/a"
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/git/fetches/1"
    }
  }
}

Git fetch

View
GET/naut/project/{project_id}/git/fetches/{fetch_id}

Example URI

GET /naut/project/stack1/git/fetches/1
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

fetch_id
number (required) Example: 1

ID of the git fetch

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "fetches",
    "id": 1,
    "attributes": {
      "status": "Complete"
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/git/fetches/1"
    }
  }
}

Deployments

Deployments collection

List all
GET/naut/project/{project_id}/environment/{environment_id}/deploys{?deployer_email,state,lastedited_from_unix,datestarted_from_unix,datestarted_to_unix,summary,title}

Returns a list of deployments associated to the environment.

Example URI

GET /naut/project/stack1/environment/Production/deploys?deployer_email=joe@example.com&state=New&lastedited_from_unix=1267148625&datestarted_from_unix=1267148625&datestarted_to_unix=4075753425&summary=We fixed all the bugs in this deployment&title=Deployment of site v1.0.0
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

deployer_email
string (optional) Example: joe@example.com

Filter by deployer

state
string (optional) Example: New

Filter by state, one of New,Submitted,Invalid,Approved,Rejected,Queued,Deploying,Aborting,Completed,Failed,Deleted

lastedited_from_unix
int (optional) Example: 1267148625

Include only deployments edited after this timestamp

datestarted_from_unix
int (optional) Example: 1267148625

Include only deployments started after this timestamp

datestarted_to_unix
int (optional) Example: 4075753425

Include only deployments started before this timestamp

title
string (optional) Example: Deployment of site v1.0.0

Filter by title

summary
string (optional) Example: We fixed all the bugs in this deployment

Filter by summary

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": [
    {
      "type": "deployments",
      "id": 1,
      "attributes": {
        "id": 1,
        "date_created_unix": 1388534400,
        "date_started_unix": 1388534400,
        "date_requested_unix": 1388534400,
        "date_updated_unix": 1388534400,
        "title": "Deployment of site v1.0.0",
        "summary": "We fixed all the bugs in this deployment",
        "deployment_type": "code-only",
        "deployment_estimate": "2",
        "sha": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
        "short_sha": "257e0c0",
        "commit_subject": "Update README.md",
        "commit_message": "Update README.md",
        "commit_url": "https://github.com/mateusz/blank/commit/257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
        "deployer": {
          "id": 1,
          "email": "joe@example.com",
          "role": "Stack Manager",
          "name": "Joe Bloggs"
        },
        "state": "Completed",
        "is_current_build": false
      },
      "relationships": {
        "environment": {
          "data": {
            "type": "environments",
            "id": "prod",
            "links": {
              "self": "http://example.com/naut/project/stack1/environment/Production"
            }
          }
        },
        "stack": {
          "data": {
            "type": "stacks",
            "id": "stack1",
            "links": {
              "self": "http://example.com/naut/project/stack1"
            }
          }
        }
      },
      "links": {
        "self": "http://example.com/naut/project/stack1/environment/Production/deploys/1"
      }
    }
  ]
}

Create
POST/naut/project/{project_id}/environment/{environment_id}/deploys

Create a deployment.

If ref_type is set to “promote_from_uat” or “redeploy”, pass empty ref - otherwise it takes precedence, deploying potentially something unexpected.

Example URI

POST /naut/project/stack1/environment/Production/deploys
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

Request
HideShow
Body
{
  "ref": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
  "ref_type": "sha",
  "title": "Deployment of site v1.0.0",
  "summary": "We fixed all the bugs in this deployment",
  "bypass": false,
  "bypass_and_start": true,
  "schedule_start_unix": 1511830104,
  "schedule_end_unix": 1511837304,
  "locked": false
}
Schema
{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "description": "Commit reference. Can be a branch, tag, or SHA"
    },
    "ref_type": {
      "enum": [
        "promote_from_uat",
        "sha",
        "branch",
        "tag",
        "redeploy"
      ],
      "description": "Type of commit reference"
    },
    "title": {
      "type": "string",
      "description": "Title of the deployment"
    },
    "summary": {
      "type": "string",
      "description": "Summary of the deployment in more detail"
    },
    "bypass": {
      "type": "boolean",
      "description": "Bypass approval of deployment. Only possible if user has permission to do so"
    },
    "bypass_and_start": {
      "type": "boolean",
      "description": "Bypass approval of deployment and start immediately. Only possible if user has permission to do so"
    },
    "schedule_start_unix": {
      "type": "integer",
      "description": "Scheduled start time for deployment. Currently only used internally"
    },
    "schedule_end_unix": {
      "type": "integer",
      "description": "Scheduled end time for deployment. Currently only used internally"
    },
    "locked": {
      "type": "boolean",
      "description": "Prevent deployment from being deleted or changed by other users"
    }
  },
  "required": [
    "ref_type"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  201
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "deployments",
    "id": 1,
    "attributes": {
      "id": 1,
      "date_created_unix": 1388534400,
      "date_started_unix": 1388534400,
      "date_requested_unix": 1388534400,
      "date_updated_unix": 1388534400,
      "title": "Deployment of site v1.0.0",
      "summary": "We fixed all the bugs in this deployment",
      "changes": {
        "Code version": {
          "from": "-",
          "to": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5"
        }
      },
      "deployment_type": "code-only",
      "deployment_estimate": "2",
      "sha": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
      "short_sha": "257e0c0",
      "commit_subject": "Update README.md",
      "commit_message": "Update README.md",
      "commit_url": "https://github.com/mateusz/blank/commit/257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
      "deployer": {
        "id": 1,
        "email": "joe@example.com",
        "role": "Stack Manager",
        "name": "Joe Bloggs"
      },
      "state": "Queued",
      "is_current_build": true
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/environment/Production/deploys/1"
    }
  }
}

Deployment

View
GET/naut/project/{project_id}/environment/{environment_id}/deploys/{deployment_id}

Obtain information about a deployment.

Example URI

GET /naut/project/stack1/environment/Production/deploys/1
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

deployment_id
number (required) Example: 1

ID of the deployment

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "deployments",
    "id": 1,
    "attributes": {
      "id": 1,
      "date_created_unix": 1388534400,
      "date_started_unix": 1388534400,
      "date_requested_unix": 1388534400,
      "date_updated_unix": 1388534400,
      "title": "Deployment of site v1.0.0",
      "summary": "We fixed all the bugs in this deployment",
      "deployment_type": "code-only",
      "deployment_estimate": "2",
      "sha": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
      "short_sha": "257e0c0",
      "commit_subject": "Update README.md",
      "commit_message": "Update README.md",
      "commit_url": "https://github.com/mateusz/blank/commit/257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
      "deployer": {
        "id": 1,
        "email": "joe@example.com",
        "role": "Stack Manager",
        "name": "Joe Bloggs"
      },
      "state": "Completed",
      "is_current_build": false
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/environment/Production/deploys/1"
    }
  }
}

Delete
DELETE/naut/project/{project_id}/environment/{environment_id}/deploys/{deployment_id}

Delete the deployment. This operation is irreversible.

Example URI

DELETE /naut/project/stack1/environment/Production/deploys/1
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

deployment_id
number (required) Example: 1

ID of the deployment

Response  204

Start deployment

Start
POST/naut/project/{project_id}/environment/{environment_id}/deploys/start

Example URI

POST /naut/project/stack1/environment/Production/deploys/start
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

Request
HideShow
Body
{
  "id": 2
}
Schema
{
  "type": "string",
  "properties": {
    "id": {
      "type": "integer",
      "description": "ID of deployment"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "deployments",
    "id": 2,
    "attributes": {
      "id": 2,
      "date_created_unix": 1388534400,
      "date_started_unix": 1388534400,
      "date_requested_unix": 1388534400,
      "date_updated_unix": 1388534400,
      "title": "Deployment of site v1.0.0",
      "summary": "We fixed all the bugs in this deployment",
      "changes": {
        "Code version": {
          "from": "-",
          "to": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5"
        }
      },
      "deployment_type": "code-only",
      "deployment_estimate": "2",
      "sha": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
      "short_sha": "257e0c0",
      "commit_subject": "Update README.md",
      "commit_message": "Update README.md",
      "commit_url": "https://github.com/mateusz/blank/commit/257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
      "deployer": {
        "id": 1,
        "email": "joe@example.com",
        "role": "Stack Manager",
        "name": "Joe Bloggs"
      },
      "state": "Queued",
      "is_current_build": true
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/environment/Production/deploys/1"
    }
  }
}

Invalidate deployment

Mark an approved deployment as invalid. This is useful for marking an older submitted, or approved deployment as no longer relevant if there is a new one that supersedes it.

Invalidate
POST/naut/project/{project_id}/environment/{environment_id}/deploys/invalidate

Example URI

POST /naut/project/stack1/environment/Production/deploys/invalidate
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

Request
HideShow
Body
{
  "id": 2
}
Schema
{
  "type": "string",
  "properties": {
    "id": {
      "type": "integer",
      "description": "ID of deployment"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "deployments",
    "id": 2,
    "attributes": {
      "id": 2,
      "date_created_unix": 1388534400,
      "date_started_unix": 1388534400,
      "date_requested_unix": 1388534400,
      "date_updated_unix": 1388534400,
      "title": "Deployment of site v1.0.0",
      "summary": "We fixed all the bugs in this deployment",
      "changes": {
        "Code version": {
          "from": "-",
          "to": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5"
        }
      },
      "deployment_type": "code-only",
      "deployment_estimate": "2",
      "sha": "257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
      "short_sha": "257e0c0",
      "commit_subject": "Update README.md",
      "commit_message": "Update README.md",
      "commit_url": "https://github.com/mateusz/blank/commit/257e0c0a2441e6c2d52b654cf70d819b4ed79de5",
      "deployer": {
        "id": 1,
        "email": "joe@example.com",
        "role": "Stack Manager",
        "name": "Joe Bloggs"
      },
      "state": "Invalid",
      "is_current_build": true
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/environment/Production/deploys/1"
    }
  }
}

Snapshots

Snapshots collection

List all
GET/naut/project/{project_id}/snapshots

Returns a list of snapshots associated with a stack. This will include snapshots in progress - which will be identifiable by the snapshot_status of ‘pending’ and empty values for download_link and size.

Example URI

GET /naut/project/stack1/snapshots
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": [
    {
      "type": "snapshots",
      "id": 1,
      "attributes": {
        "created": "2014-07-02 00:00:00",
        "mode": "db",
        "can_download": "true",
        "can_delete": "true",
        "size": "2096",
        "snapshot_status": "complete"
      },
      "relationships": {
        "source": {
          "data": [
            {
              "type": "environments",
              "id": "Production",
              "links": {
                "self": "http://example.com/naut/project/stack1/environment/Production"
              }
            }
          ]
        },
        "owner": {
          "data": [
            {
              "type": "environments",
              "id": "UAT",
              "links": {
                "self": "http://example.com/naut/project/stack1/environment/UAT"
              }
            }
          ]
        }
      },
      "links": {
        "download_link": "https://dash.cwp.govt.nz/path/to/snapshot.sspak"
      }
    }
  ]
}

Create
POST/naut/project/{project_id}/snapshots

Create a snapshot of an environment associated with a stack. The response immediately returned will contain a location, which will return a HTTP 204 response until the snapshot has completed. At that point, the response will change to HTTP 200, and the download link will be returned.

Example URI

POST /naut/project/stack1/snapshots
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

Request
HideShow
Body
{
  "environment": "Production",
  "mode": "all"
}
Schema
{
  "type": "object",
  "properties": {
    "environment": {
      "type": "string",
      "description": "Name of the environment"
    },
    "mode": {
      "enum": [
        "all",
        "db",
        "assets"
      ],
      "description": "Type of the snapshot to make"
    }
  },
  "required": [
    "environment",
    "mode"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  202
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "transfers",
    "id": 1,
    "attributes": {
      "status": "n/a"
    },
    "relationships": {
      "snapshot": {
        "data": null
      }
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/snapshots/transfer/1"
    }
  }
}

Snapshot

View
GET/naut/project/{project_id}/snapshots/{snapshot_id}

Obtain information about a snapshot.

Example URI

GET /naut/project/stack1/snapshots/1
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

snapshot_id
number (required) Example: 1

ID of the snapshot

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "snapshots",
    "id": 1,
    "attributes": {
      "created": "2014-07-02 00:00:00",
      "mode": "db",
      "can_download": "true",
      "can_delete": "true",
      "size": "2096",
      "snapshot_status": "complete"
    },
    "relationships": {
      "source": {
        "data": [
          {
            "type": "environments",
            "id": "Production",
            "links": {
              "self": "http://example.com/naut/project/stack1/environment/Production"
            }
          }
        ]
      },
      "owner": {
        "data": [
          {
            "type": "environments",
            "id": "UAT",
            "links": {
              "self": "http://example.com/naut/project/stack1/environment/UAT"
            }
          }
        ]
      }
    },
    "links": {
      "download_link": "https://dash.cwp.govt.nz/path/to/snapshot.sspak"
    }
  }
}

Delete
DELETE/naut/project/{project_id}/snapshots/{snapshot_id}

Delete the snapshot. This operation is irreversible.

Example URI

DELETE /naut/project/stack1/snapshots/1
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

snapshot_id
number (required) Example: 1

ID of the snapshot

Response  204

Transfer

Transfers represent snapshotting operations in progress.

View
GET/naut/project/{project_id}/snapshots/transfer/{transfer_id}

Obtain information about a transfer.

Example URI

GET /naut/project/stack1/snapshots/transfer/1
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

transfer_id
number (required) Example: 1

ID of the transfer

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "transfers",
    "id": 1,
    "attributes": {
      "status": "Finished"
    },
    "relationships": {
      "snapshot": {
        "data": {
          "type": "snapshots",
          "id": 1,
          "links": {
            "self": "http://example.com/naut/project/stack1/snapshots/1"
          }
        }
      }
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/snapshots/transfer/1"
    }
  }
}

Environment lock

Environment lock

Lock
POST/naut/project/{project_id}/environment/{environment_id}/lock

Lock an environment so that deployments and snapshots cannot be performed.

Example URI

POST /naut/project/stack1/environment/Production/lock
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

Request
HideShow
Body
{
  "lock_message": "This environment is currently under maintenance"
}
Schema
{
  "type": "object",
  "properties": {
    "lock_message": {
      "type": "string",
      "description": "Reason for lock"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  202
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "environmentlock",
    "id": "stack1:Production",
    "attributes": {
      "locked": true,
      "lock_message": "This environment is currently under maintenance"
    }
  }
}

Unlock
DELETE/naut/project/{project_id}/environment/{environment_id}/lock

Removes an existing environment lock.

Example URI

DELETE /naut/project/stack1/environment/Production/lock
URI Parameters
HideShow
project_id
string (required) Example: stack1

Name of the stack

environment_id
string (required) Example: Production

Name of the environment

Response  204

Manifest Releases

Manifest Releases collection

List all
GET/naut/manifestreleases

Returns a list of infrastructure manifest releases.

Example URI

GET /naut/manifestreleases
Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": [
    {
      "type": "manifestreleases",
      "id": "1",
      "attributes": {
        "sha": "3.17.3",
        "released_unix": 1513006144
      }
    }
  ]
}

Generated by aglio on 14 May 2018