API Documentation

The developer API is designed to enable users to integrate FTPloy into their applications and services. The API is JSON and RESTful, and all aspects of FTPloy are open to developers via basic auth.

Current API domain:

https://ftploy.com/api/1.0/

Overview

All API access is over HTTPS through the ftploy.com/api/1.0/ url. Everything sent and receieved is JSON. The FTPloy API is not currently limited, however that is due to change in the future.

$ curl -u username:password -i https://ftploy.com/api/1.0/deployments
HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
Cache-Control: no-cache
Content-Type: application/json
Date: Tue, 02 Jul 2013 22:11:14 GMT

Errors

Errors are returned in the following format.

{"error": "Missing required fields. Please refer to documentation."}

Response codes are as follows:

Notes


Projects

GET: All projects

URL

https://ftploy.com/api/1.0/projects

Curl

$ curl -u username:password -i https://ftploy.com/api/1.0/projects

Response

[
    {
        "id": 1,
        "repo": "steve228uk/laravel",
        "name": "Laravel",
        "host": "example.com",
        "path": "/public_html/",
        "username": "username",
        "service": "bitbucket",
        "created_at": "2012-11-19 02:27:45",
        "updated_at": "2013-06-09 20:46:25",
        "secret": "xxxxxxxxxxxxxxxxxxxxxxx",
        "port": 22,
        "branch": "master",
        "active": 1,
        "posthook": null,
        "prehook": null,
        "server_id": null
    },
    ...
]

An empty JSON array will be returned should the user have no projects available.

POST: Create new project

The following will return a JSON object of the newly created project if successful.

URL

https://ftploy.com/api/1.0/projects

Curl

$ curl -u username:password -d "name=FTPloy&repo=steve228uk/ftploy&path=/path/to..." -i https://ftploy.com/api/1.0/projects

Input

The following must be passed through as POST data.

Field Description Details
name The name of the project as used on FTPloy Required string
repo The repository in username/repo format Required string
path Server path to be deployed to Required string
service Either github or bitbucket Required string
server_id ID of saved server Required if host not set integer
host Server host address Required if server_id not set string
username Server username Required if server_id not set string
password Server password Required if server_id not set string
port Server port Required if server_id not set integer
dir Directory to deploy from Optional string
branch Branch to deploy from. Bitbucket only. Optional string
posthook Post-deploy hook. SSH only. Optional string
prehook Pre-deploy hook. SSH only. Optional string
deploynow Trigger a deploy now upon project creation. Optional boolean

Response

The newly created project will be returned.

{
    "id": 1,
    "repo": "steve228uk/laravel",
    "name": "Laravel",
    "host": "example.com",
    "path": "/public_html/",
    "username": "username",
    "service": "bitbucket",
    "created_at": "2012-11-19 02:27:45",
    "updated_at": "2013-06-09 20:46:25",
    "secret": "xxxxxxxxxxxxxxxxxxxxxxx",
    "port": 22,
    "branch": "master",
    "active": 1,
    "posthook": null,
    "prehook": null,
    "server_id": null
}

GET: Single project

URL

https://ftploy.com/api/1.0/projects/:id

Curl

$ curl -u username:password -i https://ftploy.com/api/1.0/projects/1

Response

{
    "id": 1,
    "repo": "steve228uk/laravel",
    "name": "Laravel",
    "host": "example.com",
    "path": "/public_html/",
    "username": "username",
    "service": "bitbucket",
    "created_at": "2012-11-19 02:27:45",
    "updated_at": "2013-06-09 20:46:25",
    "secret": "xxxxxxxxxxxxxxxxxxxxxxx",
    "port": 22,
    "branch": "master",
    "active": 1,
    "posthook": null,
    "prehook": null,
    "server_id": null
}

PUT: Single project

URL

https://ftploy.com/api/1.0/projects/:id

Curl

$ curl -X PUT -u username:password -i  https://ftploy.com/api/1.0/projects/1

Input

The following must be passed through as POST data. You can modify as many or as few as you like.

Field Description Details
name The name of the project as used on FTPloy string
repo The repository in username/repo format string
path Server path to be deployed to string
service Either github or bitbucket string
server_id ID of saved server integer
host Server host address string
username Server username string
password Server password string
port Server port integer
dir Directory to deploy from string
branch Branch to deploy from. Bitbucket only. string
posthook Post-deploy hook. SSH only. string
prehook Pre-deploy hook. SSH only. string

Response

{
    "id": 1,
    "repo": "steve228uk/laravel",
    "name": "Laravel",
    "host": "example.com",
    "path": "/public_html/",
    "username": "username",
    "service": "bitbucket",
    "created_at": "2012-11-19 02:27:45",
    "updated_at": "2013-06-09 20:46:25",
    "secret": "xxxxxxxxxxxxxxxxxxxxxxx",
    "port": 22,
    "branch": "master",
    "active": 1,
    "posthook": null,
    "prehook": null,
    "server_id": null
}

DELETE: Single project

URL

https://ftploy.com/api/1.0/projects/:id

Curl

$ curl -X DELETE -u username:password -i  https://ftploy.com/api/1.0/projects/1

Response

{"message": "Project deleted successfully"}

Servers

GET: All servers

URL

https://ftploy.com/api/1.0/servers

Curl

$ curl -u username:password -i https://ftploy.com/api/1.0/servers

Response

[
    {
        "id": 1,
        "name": "WebFaction",
        "host": "example.com",
        "username": "username",
        "port": 22,
        "created_at": "2013-06-30 15:57:53",
        "updated_at": "2013-06-30 15:57:53"
    },
    ...
]

An empty JSON array will be returned should the user have no servers available.

POST: Create new server

URL

https://ftploy.com/api/1.0/servers

Curl

$ curl -u username:password -d "name=Webfaction&host=domain.com..." -i https://ftploy.com/api/1.0/servers

Input

The following must be passed through as POST data.

Field Description Details
name The name of the server as used on FTPloy Required string
host The server host Required string
username The server username Required string
password The server password Required string
port The Server port Required integer

Response

{
    "id": 1,
    "name": "WebFaction",
    "host": "example.com",
    "username": "username",
    "port": 22,
    "created_at": "2013-06-30 15:57:53",
    "updated_at": "2013-06-30 15:57:53"
}

GET: Single server

URL

https://ftploy.com/api/1.0/servers/:id

Curl

$ curl -u username:password -i https://ftploy.com/api/1.0/servers/1

Response

{
    "id": 1,
    "name": "WebFaction",
    "host": "example.com",
    "username": "username",
    "port": 22,
    "created_at": "2013-06-30 15:57:53",
    "updated_at": "2013-06-30 15:57:53"
}

PUT: Update single server

URL

https://ftploy.com/api/1.0/servers/:id

Curl

$ curl -X PUT -u username:password -d "name=Krystal&host=krystal.co.uk" -i https://ftploy.com/api/1.0/servers/1

Input

The following must be passed through as POST data. You can update as many or as few fields as required.

Field Description Details
name The name of the server as used on FTPloy string
host The server host string
username The server username string
password The server password string
port The Server port integer

Response

The updated server object will be returned.

{
    "id": 1,
    "name": "WebFaction",
    "host": "example.com",
    "username": "username",
    "port": 22,
    "created_at": "2013-06-30 15:57:53",
    "updated_at": "2013-06-30 15:57:53"
}

DELETE: Single server

URL

https://ftploy.com/api/1.0/servers/:id

Curl

$ curl -X DELETE -u username:password -i  https://ftploy.com/api/1.0/servers/1

Response

{"message": "Server deleted successfully"}

Deployments

GET: All deployments

URL

https://ftploy.com/api/1.0/deployments

Curl

$ curl -u username:password -i https://ftploy.com/api/1.0/deployments

Parameters

Parameters are passed through on the URL as a query string.

Parameter Description
page Page of deployments to fetch; 50 per page
project Project ID to filter by.

Response

If the associated project is available it will be added under the project key and the message key will also be populated.

[
    {
        "id": 1,
        "project_id": 180,
        "commit_id": "ff5caf549bb2",
        "service": "bitbucket",
        "created_at": "2012-11-25 18:44:24",
        "updated_at": "2012-11-25 18:44:24",
        "message": "Test commit 2\n",
        "project": {
            "id": 180,
            "repo": "steve228uk/cocoon-site",
            "name": "Cocoon Site",
            "host": "webfaction.com",
            "path": "/public_html/",
            "username": "username",
            "service": "bitbucket",
            "created_at": "2012-11-19 21:27:39",
            "updated_at": "2013-06-09 20:46:25",
            "secret": "xxxxxxxxxxx",
            "port": 22,
            "branch": "master",
            "active": 1,
            "posthook": null,
            "prehook": null,
            "server_id": null
        }
    },
    {
        "id": 2,
        "project_id": 1,
        "commit_id": "xxxxxxxxxxxx",
        "service": "bitbucket",
        "created_at": "2012-11-03 14:09:24",
        "updated_at": "2012-11-03 14:09:24"
    },
    ...
]

An empty JSON array will be returned should the user have no deployments available.

GET: Single deployment

URL

https://ftploy.com/api/1.0/deployments/:id

Curl

$ curl -u username:password -i https://ftploy.com/api/1.0/deployments/1

Response

{
    "id": 1,
    "project_id": 1,
    "commit_id": "xxxxxxxxxxxx",
    "service": "bitbucket",
    "created_at": "2012-11-03 14:09:24",
    "updated_at": "2012-11-03 14:09:24"
}

Repositories

GET: All repositories

URL

https://ftploy.com/api/1.0/repositories

Curl

$ curl -u username:password -i https://ftploy.com/api/1.0/repositories

Response

{
    "github": [
        {
            "name": "FTPloy",
            ...
        },
        ...
    ],
    "bitbucket": [
        {
            "name": "FTPloy",
            ...
        },
        ...
    ]
}

Empty JSON arrays will be returned should the user not have any repositories or not be connected to GitHub or Bitbucket

GET: Service repositories

URL

https://ftploy.com/api/1.0/repositories/:service

Curl

$ curl -u username:password -i https://ftploy.com/api/1.0/repositories/bitbucket

Response

[
    {
        "scm": "git",
        "has_wiki": false,
        "last_updated": "2012-11-07 22:26:19",
        "creator": null,
        "created_on": "2012-11-07 22:23:52",
        "owner": "steve228uk",
        ...
    },
    ...
}

Empty JSON arrays will be returned should the user not have any repositories or not be connected to GitHub or Bitbucket