Docs: Introduction

Mon, 01 Jan 0001 00:00:00 +0000

FS is a simple file storage with simple rest api.

Access

Endpoint: https://apps.moinz.de/fs/fs.php. See the API page for details.

Authorization

Access to paths can be finely tuned by an admin (TBD: provide an iam api). Policies can control access to various resources based on username, action and paths.

The authorization guide documents the Policy concept.

Clients

fs.bash - Small bash wrapper around curl.

Docs: Objects API

Mon, 01 Jan 0001 00:00:00 +0000

The Objects API is accessable under the following URL:

http://apps.moinz.de/fs/fs.php

Generally all API responses are JSON responses, if not stated otherwise. If the URL parameter pretty is set, the responses will be pretty printed.

NOTE: All examples below are slightly pretty-printed for easier readability.

Authentication

Authentication can happen over Basic Auth or using JWT as a bearer token and cookies. A token can be obtained by contacting support.

NOTE: For all examples below that an authentication header is passed.

Operations

Listing objects

Lists all objects in the bucket. Use query parameter prefix to define a common prefix string. If given, it must start with a /.

GET /fs/fs.php?prefix=/

{
 "prefix": "/",
 "objects": [
 {"key": "/docs/api.md", "acl":"public-read", "size": 100, "mtime": "2015-10-10T19:00:00Z", "mime": "plain/text"},
 {"key": "/README.md", "acl": "public-read", size": 100, "mtime": "2015-10-10T19:00:00Z", "mime": "plain/text"}
 ]
}

By default, all objects are listed. If you just want to discover, you can pass delimiter=/, which splits the keys and list the prefix in the field common-prefixes. In combination with the prefix parameter this allows to list files and folders easily.

GET /fs/fs.php?prefix=/&delimiter=/

{
 "prefix": "/",
 "delimiter": "/",
 "common-prefixes": [
 "/docs/"
 ],
 "objects": [
 {"key": "/README.md", "acl": "public-read", size": 100, "mtime": "2015-10-10T19:00:00Z", "mime": "plain/text"}
 ]
}

GET /fs/fs.php?prefix=/docs&delimiter=/

{
 "prefix": "/docs",
 "delimiter": "/",
 "objects": [
 {"key": "/docs/api.md", "acl":"public-read", "size": 100, "mtime": "2015-10-10T19:00:00Z", "mime": "plain/text"}
 ]
}

Get Object

To read the contents of an objects, provide the key to the object behind the endpoint url. The content-type will be determined by the server.

GET /fs/fs.php/docs/api.md

A 404 Not Found will be returned, if the given key does not exist. Otherwise a 200 OK. If the file has the public-read acl, no authorization is required.

A header x-acl contains the ACL of the object.

PS: HEAD is also supported.

Create an Object

Simply use PUT with the desired key and provide the content in the body.

PUT /fs/fs.php/demo.md

This is the new content

The server responds with a 201 Created if the upload was successful.

You can specify a x-acl header field, which can be either private or public-read. private is the default. When set to public-read, reading this file does not require authentication.

Deleting an Object

Use DELETE to delete an undesired object.

DELETE /fs/fs.php/demo.md

The server responds with a 204 No Content if the delete was successful. If no such key exists, a 404 Not Found is returned.

Updating an Objects ACL

You can change the ACL of an object after it was created by issuing a PUT to the ?acl resource.

PUT /fs/fs.php/demo.md?acl

public-read

The servers responds with a 204 No Content. A 400 Bad Request indicates a wrong ACL.

Workarounds

All object keys can optionally end in .ignore which will be dropped when reading/writing. fs.bash appends this automatically to all routes.

Docs: CLI

Mon, 01 Jan 0001 00:00:00 +0000

A cli is available as fs-client-go.

It supports the following subcommands:

ls PREFIX
delete KEY
set KEY CONTENT
set-acl KEY ACL
push KEY PATH
url KEY

Moinz.de Webservices – FS

Docs: Introduction

Access

Authorization

Clients

Docs: Objects API

Authentication

Operations

Listing objects

Get Object

Create an Object

Deleting an Object

Updating an Objects ACL

Workarounds

Docs: CLI