Brinkbit HTTP Filesystem API

A generalized RESTful API for managing a remote file system

Table of Contents

1. Overview
2. Resources
3. Request
4. Response
5. Actions
6. Get 1. read 1. alias 1. search 1. inspect 1. download
7. Post 1. create 1. bulk 1. copy
8. Put 1. update 1. move 1. rename
9. Delete 1. destroy
10. Contribution

⬆ back to top

Overview

This API is intended to be the standard for communication between the client and server for the filesystem component of the Brinkbit IDE. While our use case is specific, we hope to develop this as a generalized implementation-agnostic standard for managing remote file systems via HTTP requests.

The http-fs-api follows the RESTful API systems architecture style. What this means in practice is that all actions are mapped to four HTTP methods (POST, GET, PUT, DELETE) which in turn represent the four CRUD commands (Create, Read, Update, Delete). The requested url contains a uri component which determines what resource will be manipulated.

While the API is designed to handle paths, directories, and files as though the backend were an actual file system, it's important to note that your backend implementation does not need to be an actual filesystem. In fact, we recommend that you not store the manipulated resources on an actual filesystem but use some other form of data storage i.e. a database or S3 Buckets.

All examples contained in this document are written as HTTP requests, with the fictitious http://animals.com as the domain. In all the examples, pets/ will be the route on which the file system API is defined. The structure of the file system is as follows:

TODO: replace with graphic.

• pets/
  • cats/
    • siamese.jpg
    • cat_adjectives.txt
    • kindof_pretty_cat.png
    • very_pretty_cat.gif
    • cat_names.txt
    • more_pretty_cats/
  • dogs/
    • golden_retriever.bmp
    • loyal_companion.png

⬆ back to top

Resources

Our filesystem has two types of resources, files and directories. Both can be manipulated with the same actions, but each behave a little differently.

Files are discrete, independent resources, containing metadata specifically to itself and their own data. Files must live either at the top level of the file system, or within a directory.

Directories are containers for files and other directories, containing metadata for itself, as well as aggregated data concerning it's contents. They are denoted by a trailing slash, following their name, e.g., "more_pretty_cats/"

⬆ back to top

Request

Requests are made on a uri with one of the following four HTTP methods: "GET", "POST", "PUT", "DELETE".

A uri represents the resource to take action on. For example the uri /cats/siamese.jpg

A JSON object MUST be at the root of every JSON API request containing data. This object defines a document's "top level". Every request containing a JSON object MUST have a data field at the top level

{
  "data": {
    //...
  }
}

A request MAY specify an action string field within the data field. If no action is specified, then the associated default behavior occurs. Each action field has a set of accepted parameters, and the API MUST return a 400 status if a mismatch occurs. Note that each method's default has it's own alias, for consistency.

{
  "data": {
    "action": "move",
    //...
  }
}

The request MAY have a parameters field with the data field, which contains specific parameters for the given action. If there is no action field, the entire parameters field is ignored.

{
  "data": {
    "action": "move",
    "parameters": {
      "destination": "dogs/",
      //...
    }
  }
}

The parameters field MAY also contain a flags field, which is an array of strings representing aliased flags which alter the specified action. The current list of flags are:

force / f: force operation

recursive / r: recursive

unique / u: force uniqueness.

Finishing out the example, to move the siamese.jpg resource from the /cats/ directory to the /dogs/ directory, overwriting any resource there that shares the name, you would send the following request:

PUT /cats/siamese.jpg HTTP/1.1
Content-Type: application/fs.api+json
Accept: application/fs.api+json

{
  "data": {
    "action": "move",
    "parameters": {
      "destination": "dogs/",
      "flags": [ "force" ]
    },
  }
}

⬆ back to top

Response

Similar to the request syntax, most responses SHOULD have a JSON object at the root of the response when it contains data, which defines the response's "top level". The only exceptions to this are the successful read and download responses, which MUST only contain the resource's data. Every other response MUST have a data field at the top level on success, or an errors field on failure. It MUST NOT have both. The root level response MAY contain a metadata field that contains relevant or more descriptive data. The root level of a JSON response MUST NOT contain any fields besides data, error, and metadata.

A successful response will have all relevant data inside of a top-level data array, e.g.:

{
  "data": [
    "file1",
    "file2",
    "folder/"
  ]
}

An error response WILL have a JSON object at the root, and WILL have an errors field at the top level. The errors field isan array of at least one JSON object containing only a status field and message field. The status field should be a numerical status code representing the error condition, and the 'message' field should be a human-readable string giving additional information. E.g.:

{
  "errors": [
    {
      "status": 404,
      "message": "File not found."
    }
  ]
}

⬆ back to top

Actions

action is an optional parameter under data which gives direction for what operation will take place on the specified resource, or set of resources. Each action has an associated HTTP method, and only the actions associated with that HTTP method are accepted. If a mismatch between HTTP method and action occurs, the API MUST return a 400 status. The list of actions per method are as follows:

• GET: read, search, inspect, download
• POST: create, bulk, copy
• PUT: update, move, rename
• DELETE: destroy

Get

- 1.1 read default

Request file or directory contents. Default GET action.

Parameters

none

Flags

none

The implementation MAY support the following flag:

• recursive - return an array of children resources and all of their children resources relative to the requested resource

Request file:

GET /cats/siamese.jpg HTTP/1.1
Accept: application/vnd.api+json

Response:

Raw image data

Request directory:

GET /cats/ HTTP/1.1
Accept: application/vnd.api+json

Response:

{
  "data": [
    "siamese.jpg",
    "kindof_pretty_cat.png",
    "very_pretty_cat.gif",
    "morePrettyCats/"
  ]
}

Errors

• 404 - Invalid path / Resource does not exist

⬆ back to top

- 1.2 alias

Resolve a resource to an internal alias.

The implementation MAY support aliasing resources, such as by GUID, to speed up retrieving or querying resources

Parameters

none

Flags

none

Request:

GET /cats/kindof_pretty_cat.png
Accept: application/vnd.api+json

{
  "data": {
    "action": "alias"
  }
}

Response:

{
  "data": {
    "GUID": "4d2df4ed-2d77-4bc2-ba94-1d999786aa1e"
  }
}

Errors

• 404 - Resource not found

⬆ back to top

- 1.3 search

Run a query on the requested directory, and returns an array of matching resources.

Parameters

• query string - an implementation-specific query syntax supported by the API, that defines on which fields to search, and the search to be made.
• sort string optional - an implementation-specific sorting syntax supported by the API, defining which fields to sort on. If omitted, results will be returned in the manner determined by the query string.

The implementation MUST support querying the following fields:

• name
• parent

The implementation MAY support querying the following fields:

• type
• size
• dateCreated
• lastModified
• other custom fields defined by the implementation

Flags

• recursive - deep search. Defaults to shallow.

Request:

GET /cats/
Accept: application/vnd.api+json

{
  "data": {
    "action": "search",
    "parameters": {
      "query": "-name \"*pretty*\""
    }
  }
}

Response:

{
  "data": [
    "/cats/kindof_pretty_cat.png",
    "/cats/more_pretty_cats/"
  ]
}

Errors

• 400 - Action-Resource type conflict
• 404 - Invalid path

⬆ back to top

- 1.4 inspect

Request detailed information about a resource. By default, all metadata is returned; specifying fields will return only those fields.

The following parameter MUST be supported:

• fields array optional - an array of strings for each requested fields.

The following fields MUST be supported:

• name string - the name of the resource
• parent string - the parent directory

The following fields MAY be supported:

• type string - either 'file' or 'directory'
• size number - number of bytes
• dateCreated number - unix timestamp when the resource was created
• lastModified number - unix timestamp when the resource was last modified
• other custom fields defined by the implementation

Flags

none

Request:

GET /cats/kindof_pretty_cat.png
Accept: application/vnd.api+json

{
  "data": {
    "action": "inspect",
    "parameters": {
      "fields": ["type", "size", "name", "parent", "dateCreated", "lastModified"]
    }
  }
}

Response:

{
  "data": {
    "type": "file",
    "size": 1234567890,
    "name": "very_pretty_cat.png",
    "parent": "cats/",
    "dateCreated": 1439765335,
    "lastModified": 1439765353
  }
}

Errors

• 404 - Invalid path / Resource does not exist

⬆ back to top

- 1.5 download

Zip and download requested resource

Parameters

• compression string - Specify the type of compression to be used. Defaults to zip

The following compression formats MUST be supported:

• Zip

Flags

none

Request:

GET /cats/kindof_pretty_cat.png
Accept: application/vnd.api+json

{
  "data": {
    "action": "download"
  }
}

Response:

Zipped file contents

Errors

• 404 - Invalid path / Resource does not exist

⬆ back to top

Post

- 2.1 create default

Create a resource in a specified directory. Default POST action.

Parameters

• type string - either file or directory
• name string - the name of the resource
• content any format optional - the data to store in the resource, if type is file

Flags

• force - overwrite existing resource

Request:

POST /cats/new_cat_picture.jpg
Accept: application/vnd.api+json

{
  "data": {
    "action": "create",
    "parameters": {
      "content": "raw image data"
    }
  }
}

Response:

HTTP Status 200

Errors

• 400 - Action-Resource type conflict
• 409 - Invalid path / Resource already exists
• 415 - Invalid file type
• 413 - Request data too large

⬆ back to top

- 2.2 bulk

Upload multiple resources, or the full content of a directory, to a specified directory.

Parameters

none

Flags

• force - overwrite existing resource

Request:

POST /cats/
Accept: application/vnd.api+json
ContentType: multipart/form-data

{
  "data": {
    "action": "bulk"
  }
}

Response:

HTTP Status 200

Errors

• 400 - Action-Resource type conflict
• 409 - Invalid path / Resource already exists
• 415 - Invalid file type
• 413 - Request data too large

⬆ back to top

- 2.3 copy

Copy a resource

Parameters

• destination string - the full path to where the copy should be created. Defaults to the specified resource's directory.

Flags

• unique - rename the resource in the typical "filename_XXXX.jpg" format if there is a naming conflict.
• force - overwrite any existing resource

Request:

POST /cats/fluffy.jpg
Accept: application/vnd.api+json

{
  "data": {
    "action": "copy",
    "parameters": {
      "destination": "./"
    }
  }
}

Response: http Status 200

Errors

• 400 - Action-Resource type conflict
• 404 - Invalid path / Resource does not exist
• 409 - Invalid destination / Resource already exists

⬆ back to top

Put

- 3.1 update default

Modify an existing resource. Default PUT action

Parameters

• content any format - the data to store in the resource

Flags

• force - create resource if it does not exist

Request:

PUT /cats/cat_adjectives.txt

Accept: application/vnd.api+json

{
  "data": {
    "parameters": {
      "content": "Fluffy, Furry, Fuzzy"
    }
  }
}

Response:

HTTP Status 200

Errors

• 400 - Action-Resource type conflict
• 404 - Invalid path / Resource does not exist
• 413 - Request data too large

⬆ back to top

- 3.2 move

Relocate an existing resource

Parameters

• destination string - the path to which the resource will be moved

Flags

• force - overwrite resource if it exists

Request:

PUT /cats/cat_names.txt
Accept: application/vnd.api+json

{
  "data": {
    "action": "move",
    "parameters": {
      "destination": "cats/more_pretty_cats/"
    }
  }
}

Response:

HTTP Status 200

Errors

• 400 - Action-Resource type conflict
• 404 - Invalid path / Resource does not exist
• 409 - Invalid destination / Resource already exists

⬆ back to top

- 3.3 rename

Rename an existing resource

Parameters

• name string - the new name to give the resource

Flags

• force - overwrite resource if it exists

Request:

PUT /cats/more_pretty_cats/cat_names.txt
Accept: application/vnd.api+json

{
  "data": {
    "action": "rename",
    "parameters": {
      "name": "pretty_cat_names.txt"
    }
  }
}

Response:

HTTP Status 200

Errors

• 400 - Action-Resource type conflict
• 404 - Invalid path / Resource does not exist
• 409 - Invalid destination / Resource already exists

⬆ back to top

Delete

- 4.1 destroy default

Destroy an existing resource

Parameters

none

Flags

none

Request:

DELETE /cats/more_pretty_cats/pretty_cat_names.txt
Accept: application/vnd.api+json

Response:

HTTP Status 200

Errors

• 404 - Invalid path / Resource does not exist

⬆ back to top

Contribution

The guide for contributing to any of our repositories can be found here.

TODOs

• document global error responses
• mention resources mapping to URIs
• mention json data type