API Documentation

RESTful API

Clients access Girder servers uniformly via its RESTful web API. By providing a single, stable, consistent web API, it is possible to write multiple interchangeable clients using different technologies.

When a Girder instance is deployed, it typically also serves a page that uses Swagger to document all available RESTful endpoints in the web API and also provide an easy way for users to execute those endpoints with parameters of their choosing. In this way, the Swagger page is just the simplest and lightest client application for Girder. This page is served out of the path /api under the root path of your Girder instance.

Models

In Girder, the model layer is responsible for actually interacting with the underlying database. Model classes are where the documents representing resources are actually saved, retrieved, and deleted from the DBMS. Validation of the resource documents is also done in the model layer, and is invoked each time a document is about to be saved.

Typically, there is a model class for each resource type in the system. These models are loaded as singletons for efficiency, and can be accessed in REST resources or other models by invoking self.model('foo'), where foo is the name of the model. For example:

groups = self.model('group').list(user=self.getCurrentUser())

All models that require the standard access control semantics should extend the AccessControlledModel class. Otherwise, they should extend the Model class.

All model classes must have an initialize method in which they declare the name of their corresponding Mongo collection, as well as any collection indices they require. For example:

from girder.models.model_base import Model

class Cat(Model):
    def initialize(self):
        self.name = 'cat_collection'

The above model singleton could then be accessed via:

self.model('cat')

If you wish to use models in something other than a REST Resource or Model, either mixin or instantiate the ModelImporter class.

Model Helper Functions

Model Base

Events

User

Password

Token

Group

Collection

Folder

Item

Setting

Python API for RESTful web API

Base Classes and Helpers

User

Group

Item

Folder

Utility

Constants

Clients

jQuery Plugins

There are a set of jQuery plugins that interact with the Girder API. These can be found in the clients/jquery directory of the source tree.

$.girderBrowser(cfg)
Arguments:
  • cfg (object) – Configuration object
  • caret (boolean) – Draw a caret on main menu to indicate dropdown (true by default).
  • label (string) – The text to display in the main menu dropdown.
  • api (string) – The root path to the Girder API (/api/v1 by default).
  • selectItem (function(item,api)) – A function to call when an item is clicked. It will be passed the item’s information and the API root.
  • selectFolder (function(folder,api)) – A function to call when a folder is clicked. It will be passed the folder’s information and the API root.
  • search (boolean) – Include a search box for gathering general string search results.
  • selectSearchResult (function(result,api)) – A function to call when a search result is clicked. It will be passed the result item’s information and the API root.

This plugin creates a Bootsrap dropdown menu reflecting the current contents of a Girder server as accessible by the logged-in user. The selection on which this plugin is invoked should be an <li> element that is part of a Bootstrap navbar. For example:

<div class="navbar navbar-default navbar-fixed-top">
    <div class=navbar-header>
        <a class=navbar-brand href=/examples>Girder</a>
    </div>

    <ul class="nav navbar-nav">
        <li id=girder-browser>
            <a>Dummy</a>
        </li>
    </ul>
</div>

Then, in a JavaScript file:

$("#girder-browser").girderBrowser({
    // Config options here
    //     .
    //     .
    //     .
});

The anchor text “dummy” in the example HTML will appear in the rendered page if the plugin fails to execute for any reason. This is purely a debugging measure - since the plugin empties the target element before it creates the menu, the anchor tag (or any other content) is not required.