Beanstalk

Node Resource

This resource represents files and directories in your repository. With Node you can get directory listings and content of any file at any given revision.

New format

We are planning to gradually phase out XML support from our API and this is the first resource that’s provided only in JSON format. The format was also a bit adjusted compared to other resources: a repository object is now embedded into JSON itself, and there are no JSON root elements anymore.

Readable attributes

repository hash Embedded repository object.
name string Name of the file or directory.
path string Full path in the repository.
revision string Revision number or hash ID.
directory boolean True if node is a directory.
file boolean True if node is a file.

Additional Attributes for Files

File nodes will have the following attributes in addition to those listed above:

binary boolean True if file is binary.
mime_type string Mime-Type of the file.
language string Name of file’s programming language, if available.
size_bytes integer File size in bytes (hidden by default).
contents string File contents (hidden by default).

Additional Attributes for Directories

Directory nodes will have the following attributes in addition to those listed in the beginning of this document:

nodes array Array of sub-nodes for a directory. Each sub-node will be represented as a complete Node object.

Writable attributes

path string Path to file. Always required.
contents string File contents. Only requred on create and update requests.
commit_message string Commit message. If not specified, we will generate one for you. Optional.
branch string Repository branch. If not specified, default branch will be used. Optional.
new_name string New name for a file. Required when renaming a file.

Find Node

Find file or a directory in the repository. Several optional parameters are available:

  • path (string) — full path of the file or directory. Will be set to repository’s root directory if omitted.
  • revision (string)SVN revision number or Git hash ID of the revision that you want to browse.
  • size (boolean) — return file size for files. Inactive by default.
  • contents (boolean) — return file contents for files. Inactive by default.

Parameters size and contents can significantly slow down your API call, so use them wisely. We recommend only using them when fetching a single file.

json http-request
GET /api/repositories/{REPOSITORY_ID}/node.json?path=trunk/design

Click to expand…

json http-response
STATUS: 200

{
   "name":"design/",
   "path":"/trunk/design",
   "directory":true,
   "file":false,
   "revision":34324,
   "nodes":[
      {
         "name":"stylesheets/",
         "path":"/trunk/design/stylesheets",
         "directory":true,
         "file":false,
         "revision":34324
      },
      {
         "name":"generator.rb",
         "path":"/trunk/design/generator.rb",
         "directory":false,
         "file":true
         "revision":34324,
         "language":'ruby',
         "mime_type":"text/plain",
         "binary":false,
      }
   ],
   "repository":{
      "repository_url":"https://account.svn.beanstalkapp.com/repository",
      "title":"Awesome Repo",
      "storage_used_bytes":846254280,
      "created_at":"2012/12/10 18:29:38 -0700",
      "account_id":3346665,
      "updated_at":"2012/12/17 21:53:55 -0700",
      "type":"SubversionRepository",
      "last_commit_at":"2012/12/18 04:53:41 +0000",
      "vcs":"subversion",
      "revision":34324,
      "id":53409751,
      "anonymous":false,
      "name":"awesome-repo",
      "color_label":"label-white"
   }
}

Find Blob (Git only)

Get contents of a blob from a Git repository. Optional parameters are available:

  • id (string)SHA id of a blob object. Can be a shortened version.
  • name (string) – optional — name of the file associated with the blob, used to detect contents type. If not present, text/plain is assumed.
json http-request
GET /api/repositories/{REPOSITORY_ID}/blob.json?id=3bb0e8592a&name=test.txt

Click to expand…

json http-response
{
   "content":"# Add your own tasks in files placed in lib/tasks ending in .rake,\n# Bla bla",
   "content_type":"text/plain"
}

You can also make a raw HTTP request and receive the contents of the blob with a proper content-type inline:

raw http-request-raw
GET /api/repositories/{REPOSITORY_ID}/blob?id=3bb0e8592a&name=test.txt

Click to expand…

raw http-response
# Add your own tasks in files placed in lib/tasks ending in .rake,
# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.

require(File.join(File.dirname(__FILE__), 'config', 'boot'))

require 'rake'
require 'rake/testtask'
require 'rake/rdoctask'

require 'tasks/rails'

Create Node

Create a file in the repository.

raw http-request-raw
POST /api/repositories/{REPOSITORY_ID}/node.json
{
    "branch": "master",
    "commit_message": "Adding utility functions",
    "path": "src/utils.clj",
    "contents": "(defn- basename [path]\n(.getName (File. ^String path)))\n"
}

Click to expand…

json http-response
STATUS: 201
{
    "repository": {
        "id": {REPOSITORY_ID},
        "account_id": {ACCOUNT_ID},
        "name": "secret-background-services",
        "created_at": "2013/04/01 09:00:00 -0400",
        "updated_at": "2013/11/11 12:00:00 -0400",
        "title": "Secret Background Services",
        "color_label": "blue",
        "storage_used_bytes": 6144,
        "last_commit_at": "2013/11/14 11:15:00 -0400",
        "type": "GitRepository",
        "default_branch": "master",
        "vcs": "git",
        "repository_url": "git@{ACCOUNT}.beanstalkapp.com:/secret-background-services.git",
        "repository_url_https": "https://{ACCOUNT}.git.beanstalkapp.com/secret-background-services.git"
    },
    "name": "utils.clj",
    "path": "src/utils.clj",
    "revision": "ce1cb4e0f868de7437fe3251e7f302dca4217274",
    "directory": false,
    "file": true,
    "binary": false,
    "mime_type": "text/plain",
    "language": "Clojure"
}

Update Node

Update a file in the repository.

raw http-request-raw
PUT /api/repositories/{REPOSITORY_ID}/node.json
{
    "branch": "master",
    "path": "src/utils.clj",
    "commit_message": "Adding more utility functions",
    "contents": "(defn uuid\n[^SVNRepository repo]\n(.getRepositoryUUID repo))"
}

Click to expand…

json http-response
STATUS: 200
{
    "repository": {
        "id": {REPOSITORY_ID},
        "account_id": {ACCOUNT_ID},
        "name": "secret-background-services",
        "created_at": "2013/04/01 09:00:00 -0400",
        "updated_at": "2013/11/11 12:00:00 -0400",
        "title": "Secret Background Services",
        "color_label": "blue",
        "storage_used_bytes": 6144,
        "last_commit_at": "2013/11/15 11:01:00 -0400",
        "type": "GitRepository",
        "default_branch": "master",
        "vcs": "git",
        "repository_url": "git@{ACCOUNT}.beanstalkapp.com:/secret-background-services.git",
        "repository_url_https": "https://{ACCOUNT}.git.beanstalkapp.com/secret-background-services.git"
    },
    "name": "utils.clj",
    "path": "src/utils.clj",
    "revision": "7eec49ecf011e03da8073f03cf4ab6a124bdfc4a7",
    "directory": false,
    "file": true,
    "binary": false,
    "mime_type": "text/plain",
    "language": "Clojure"
}

Delete Node

Delete a file or directory in the repository.

raw http-request-raw
DELETE /api/repositories/{REPOSITORY_ID}/node.json
{
    "branch": "master",
    "commit_message": "Removing utility functions",
    "path": "src/utils.clj"
}

Click to expand…

json http-response
STATUS: 200
{
   "revision": "2ea0e56c2255253da807ab6a123f03cf44bdfc4a7"
}

Rename Node

Rename a file or directory in the repository.

raw http-request-raw
POST /api/repositories/{REPOSITORY_ID}/node/rename.json
{
    "branch": "master",
    "commit_message": "Renaming utility functions",
    "path": "src/utils.clj"
    "new_filename": "util_functions.clj"
}

Click to expand…

json http-response
STATUS: 200
{
    "repository": {
        "id": {REPOSITORY_ID},
        "account_id": {ACCOUNT_ID},
        "name": "secret-background-services",
        "created_at": "2013/04/01 09:00:00 -0400",
        "updated_at": "2013/11/20 12:00:00 -0400",
        "title": "Secret Background Services",
        "color_label": "blue",
        "storage_used_bytes": 6144,
        "last_commit_at": "2013/11/17 11:01:00 -0400",
        "type": "GitRepository",
        "default_branch": "master",
        "vcs": "git",
        "repository_url": "git@{ACCOUNT}.beanstalkapp.com:/secret-background-services.git",
        "repository_url_https": "https://{ACCOUNT}.git.beanstalkapp.com/secret-background-services.git"
    },
    "name": "util_functions.clj",
    "path": "src/util_functions.clj",
    "revision": "9fba49e5c2f6a24e21073f03cf4abeec2607fc4a7",
    "directory": false,
    "file": true,
    "binary": false,
    "mime_type": "text/plain",
    "language": "Clojure"
}