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'

Find SVN Properties (Subversion only)

Get information about node’s SVN properties.

json http-request

GET /api/repositories/{REPOSITORY_ID}/props.json?revision=1&path=test.txt

Click to expand…

json http-response

{
  "svn_properties":
    {
      "svn:externals": "db\t\thttp://svn.x.beanstalkapp.com/x/trunk/domain_models/db" 
    }
}

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"
}