Documentation

Overview

Package v1 contains Rufs REST API Version 1.

Admin control endpoint

/admin

The admin endpoint can be used for various admin tasks such as registering new branches or mounting known branches.

A GET request to the admin endpoint returns the current tree configuration; an object of all known branches and the current mapping:

{
    branches : [ <known branches> ],
    tree  : [ <current mapping> ]
}

A POST request to the admin endpoint creates a new tree. The body of the request should have the following form:

"<name>"

/admin/<tree>

A DELETE request to a particular tree will delete the tree.

/admin/<tree>/branch

A new branch can be created in an existing tree by sending a POST request to the branch endpoint. The body of the request should have the following form:

{
    branch : <Name of the branch>,
    rpc : <RPC definition of the remote branch (e.g. localhost:9020)>,
    fingerprint : <Expected SSL fingerprint of the remote branch or an empty string>
}

/admin/<tree>/mapping

A new mapping can be created in an existing tree by sending a POST request to the mapping endpoint. The body of the request should have the following form:

{
    branch : <Name of the branch>,
    dir : <Tree directory of the branch root>,
    writable : <Flag if the branch should handle write operations>
}

Dir listing endpoing

/dir/<tree>/<path>

The dir endpoing handles requests for the directory listing of a certain path. A request url should be of the following form:

/dir/<tree>/<path>?recursive=<flag>&checksums=<flag>

The request can optionally include the flag parameters (value should be 1 or 0) recursive and checksums. The recursive flag will add all subdirectories to the listing and the checksums flag will add checksums for all listed files.

File queries and manipulation

/file/{tree}/{path}

A GET request to a specific file will return its contents. A POST will upload a new or overwrite an existing file. A DELETE request will delete an existing file.

New files are expected to be uploaded using a multipart/form-data request. When uploading a new file the form field for the file should be named "uploadfile". The form can optionally contain a redirect field which will issue a redirect once the file has been uploaded.

A PUT request is used to perform a file operation. The request body should be a JSON object of the form (parameters are operation specific):

{
    action : <Action to perform>,
	files : <List of (full path) files which should be copied / renamed>
    newname : <New name of file (when renaming)>,
	newnames : <List of new file names when renaming multiple files using
				the files parameter>,
    destination : <Destination file when copying a single file - Destination
					directory when copying multiple files using the files
					parameter or syncing directories>
}

The action can either be: sync, rename, mkdir or copy. Copy and sync returns a JSON structure containing a progress id:

{
    progress_id : <Id for progress of the copy operation>
}

Progress information

/progress/<progress id>

A GET request to the progress endpoint returns the current progress of an ongoing operation. The result should be:

{
    "item": <Currently processing item>,
    "operation": <Name of operation>,
    "progress": <Current progress>,
    "subject": <Name of the subject on which the operation is performed>,
    "total_items": <Total number of items>,
    "total_progress": <Total progress>
}

Create zip files

/zip/<tree>

A post to the zip enpoint returns a zip file containing requested files. The files to include must be given as a list of file name with full path in the body. The body should be application/x-www-form-urlencoded encoded. The list should be a JSON encoded string as value of the value files. The body should have the following form:

files=[ "<file1>", "<file2>" ]

Index

Constants

View Source
const APIv1 = "/v1"

    APIv1 is the directory for version 1 of the API

    View Source
    const EndpointAdmin = api.APIRoot + APIv1 + "/admin/"

      EndpointAdmin is the mount endpoint URL (rooted). Handles everything under admin/...

      View Source
      const EndpointDir = api.APIRoot + APIv1 + "/dir/"

        EndpointDir is the dir endpoint URL (rooted). Handles everything under dir/...

        View Source
        const EndpointFile = api.APIRoot + APIv1 + "/file/"

          EndpointFile is the file endpoint URL (rooted). Handles everything under file/...

          View Source
          const EndpointProgress = api.APIRoot + APIv1 + "/progress/"

            EndpointProgress is the progress endpoint URL (rooted). Handles everything under progress/...

            View Source
            const EndpointZip = api.APIRoot + APIv1 + "/zip/"

              EndpointZip is the zip endpoint URL (rooted). Handles everything under zip/...

              Variables

              View Source
              var ProgressMap = datautil.NewMapCache(100, 0)

                ProgressMap contains information about copy progress.

                View Source
                var V1EndpointMap = map[string]api.RestEndpointInst{
                	EndpointAdmin:    AdminEndpointInst,
                	EndpointDir:      DirEndpointInst,
                	EndpointFile:     FileEndpointInst,
                	EndpointProgress: ProgressEndpointInst,
                	EndpointZip:      ZipEndpointInst,
                }

                  V1EndpointMap is a map of urls to endpoints for version 1 of the API

                  Functions

                  func AdminEndpointInst

                  func AdminEndpointInst() api.RestEndpointHandler

                    AdminEndpointInst creates a new endpoint handler.

                    func DirEndpointInst

                    func DirEndpointInst() api.RestEndpointHandler

                      DirEndpointInst creates a new endpoint handler.

                      func FileEndpointInst

                      func FileEndpointInst() api.RestEndpointHandler

                        FileEndpointInst creates a new endpoint handler.

                        func ProgressEndpointInst

                        func ProgressEndpointInst() api.RestEndpointHandler

                          ProgressEndpointInst creates a new endpoint handler.

                          func ZipEndpointInst

                          func ZipEndpointInst() api.RestEndpointHandler

                            ZipEndpointInst creates a new endpoint handler.

                            Types

                            type Progress

                            type Progress struct {
                            	Op            string   // Operation which we show progress of
                            	Subject       string   // Subject on which the operation is performed
                            	Progress      int64    // Current progress of the ongoing operation (this is reset for each item)
                            	TotalProgress int64    // Total progress required until current operation is finished
                            	Item          int64    // Current processing item
                            	TotalItems    int64    // Total number of items to process
                            	Errors        []string // Any error messages
                            }

                              Progress is a persisted data structure which contains the current progress of an ongoing operation.

                              func (*Progress) JSONString

                              func (p *Progress) JSONString() []byte

                                JSONString returns the progress object as a JSON string.