Back to top

Deploynaut API

This API is a newly developed interface for the Dashboard. Data structure is based on the JSON API specifications.

Using the API

In order to use the API, you will need to acquire a token via Service Desk/Helpdesk request. In order to authenticate, you should use HTTP Basic Authentication, using your email with the API token.

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: 1.0
Authorization: Basic dXNlcjp0ZXN0
Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "meta": {
    "whoami": "user",
    "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."
    }
  ]
}

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"
      },
      "relationships": {
        "environments": {
          "data": [
            {
              "type": "environments",
              "id": "Production",
              "meta": {
                "url": "http://example.com/naut/project/stack1/environment/Production"
              }
            },
            {
              "type": "environments",
              "id": "UAT",
              "meta": {
                "url": "http://example.com/naut/project/stack1/environment/UAT"
              }
            }
          ]
        }
      }
    }
  ]
}

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",
            "meta": {
              "url": "http://example.com/naut/project/stack1/environment/Production"
            }
          },
          {
            "type": "environments",
            "id": "UAT",
            "meta": {
              "url": "http://example.com/naut/project/stack1/environment/UAT"
            }
          }
        ]
      }
    }
  }
}

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

Returns a list of deployments associated to the environment.

Example URI

GET /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

Response  200
HideShow
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": [
    {
      "type": "deployments",
      "id": 1,
      "attributes": {
        "id": 1,
        "date_created": "2017-05-31 14:28:37",
        "date_created_nice": "31/05/2017 2:28pm",
        "date_created_ago": "7 days ago",
        "date_started": "2017-05-31 14:28:49",
        "date_started_nice": "31/05/2017 2:28pm",
        "date_started_ago": "7 days ago",
        "date_requested": null,
        "date_requested_nice": null,
        "date_requested_ago": null,
        "date_updated": "2017-05-31 14:30:13",
        "date_updated_nice": "31/05/2017 2:30pm",
        "date_updated_ago": "7 days ago",
        "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": "user",
          "role": "Stack Manager",
          "name": "Joe Bloggs"
        },
        "state": "Completed",
        "is_current_build": false
      },
      "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_and_start": true
}
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_and_start": {
      "type": "boolean",
      "description": "Bypass approval of deployment and start immediately. Only possible if user has permission to do so"
    }
  },
  "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": "2017-05-31 14:28:37",
      "date_created_nice": "31/05/2017 2:28pm",
      "date_created_ago": "7 days ago",
      "date_started": "2017-05-31 14:28:49",
      "date_started_nice": "31/05/2017 2:28pm",
      "date_started_ago": "7 days ago",
      "date_requested": null,
      "date_requested_nice": null,
      "date_requested_ago": null,
      "date_updated": "2017-05-31 14:30:13",
      "date_updated_nice": "31/05/2017 2:30pm",
      "date_updated_ago": "7 days ago",
      "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": "user",
        "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": "2017-05-31 14:28:37",
      "date_created_nice": "31/05/2017 2:28pm",
      "date_created_ago": "7 days ago",
      "date_started": "2017-05-31 14:28:49",
      "date_started_nice": "31/05/2017 2:28pm",
      "date_started_ago": "7 days ago",
      "date_requested": null,
      "date_requested_nice": null,
      "date_requested_ago": null,
      "date_updated": "2017-05-31 14:30:13",
      "date_updated_nice": "31/05/2017 2:30pm",
      "date_updated_ago": "7 days ago",
      "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": "user",
        "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

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",
              "meta": {
                "url": "http://example.com/naut/project/stack1/environment/Production"
              }
            }
          ]
        },
        "owner": {
          "data": [
            {
              "type": "environments",
              "id": "UAT",
              "meta": {
                "url": "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",
            "meta": {
              "url": "http://example.com/naut/project/stack1/environment/Production"
            }
          }
        ]
      },
      "owner": {
        "data": [
          {
            "type": "environments",
            "id": "UAT",
            "meta": {
              "url": "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,
          "meta": {
            "url": "http://example.com/naut/project/stack1/snapshots/1"
          }
        }
      }
    },
    "links": {
      "self": "http://example.com/naut/project/stack1/snapshots/transfer/1"
    }
  }
}

Generated by aglio on 29 Jun 2017