v1

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
• Variables
• func AdminEndpointInst() api.RestEndpointHandler
• func DirEndpointInst() api.RestEndpointHandler
• func FileEndpointInst() api.RestEndpointHandler
• func ProgressEndpointInst() api.RestEndpointHandler
• func ZipEndpointInst() api.RestEndpointHandler
• type Progress
  • func (p *Progress) JSONString() []byte

Constants

const APIv1 = "/v1"

APIv1 is the directory for version 1 of the API

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

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

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

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

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

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

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

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

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

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

Variables

var ProgressMap = datautil.NewMapCache(100, 0)

ProgressMap contains information about copy progress.

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.