Moinz.de Webservices – Docs

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: Introduction

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

Msg is a simple and small message queue for pushing and polling single messages. Topics and other more advanced mechanisms are not supported.

Access

Endpoint: https://apps.moinz.de/msg/msg.php

API

The API is documented here.

Docs: API

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

Welcome

A very simple http based message queue inspired by Amazons SNS.

Notation

Each action contains two lists: The request fields and response fields. Please note that the top level of the JSON is always an object.
The field names may contain dots to intend sub objects. In case the field denotes an array, a single uppercase letter is used, e.g. tags.N.key means the tags field contains an array containing more objects with a key field inside.
The field table may contain a required column. The notation is as followed:

Value Meaning

O Optional - the field must not be provided

R Required
Currently no pagination is supported.

Value	Meaning
O	Optional - the field must not be provided
R	Required

Authorization

The msg-php service authorizes requests over htbasic auth. Your credentials will be provided by the service operator.

DataStructures

URI

URIs are string identifiers for objects inside the msg service. They generally take the following format: msg:<type>:<unique-id>. Type is one of queue or message.

Queue

{
"id": "msg:queue:uuid()"
"tags": [
{"key": "Name", "value": "Value"},
...
]
}

QueueStatus

{
"id": "msg:queue:uuid()",
"messages": int(),
}

Message

{
"id": "string()",
"content_type": "string()",
"body": "json escaped query body",
"created_at": "ISO8601()"
}

ErrorMessage

{
"message": "string()",
["error": bool(),]
["detail": "string()",]
"code": int()
}

Actions

Generally all actions have the same format. Send a POST request to https://apps.moinz.de/msg/msg.php with a query parameter action of one of the list below. Operation parameters are given via query parameters. Data from the request body is only used when explicitly stated.

CreateQueue

Creates a new queue and returns the created queue.

Query Parameters	Required	Description
tags.N.key	O	The key for the tag. `N` must be replaced with a sequential number starting at 1 with a maximum of 20.
tags.N.value	O	The value of the tag.

Response Fields	Type	Description
queue	Queue	The queue that was created

Example

POST /msg/msg.php?action=CreateQueue&tags.1.key=name&tags.1.value=example-queue&tags.2.key=env&tags.2.value=production
Content-Length: 0
200 OK
Content-Type: application/json
{
"queue" : {
"id": "msg:queue:1234-56789-01234-5678",
"tags": {
"name": "example-queue",
"env": "production"
}
}
}

DescribeQueues

DescribeQueues fetches a list of Queues and returns them with their ids and tags to the client.

Query Parameters	Description
filter.tag:key	Filters for queues having `key` as a tag with the given value as the value.

Response Fields	Type	Description
queues	[]Queue	The queues that match the given filters

DeleteQueue

DeleteQueue deletes the specified queue and all messages contained within it.

Query Parameters	Description
queue	the URI of the queue to delete

Response Fields	Type	Description
queue	Queue	The queue that was deleted

DescribeQueueStatus

Query Parameters	Description
queue	The URI of the queue to fetch the message from

Response Fields	Type	Description
id	URI	The URI of the queue
messages	int	Number of messages in the queue

UpdateQueueTags

Updates the tags for the specified queue.

Query Parameters	Description
queue	The URI of the queue to fetch the message from
tags.N.key	The key for the tag
tags.N.value	The value of the tag

Response Fields	Type	Description
queue	Queue	The queue that got updated

PurgeQueue

PurgeQueue removes all messages currently stored in the queue.

Query Parameters	Description
queue	The URI of the queue to fetch the message from

Response Fields	Type	Description
queue	[]Queue	The queue that was purged

PushMessage

Creates a new message in the given queue. The body of the reuqest is taken as the message body, the request content-type is saved along.

Query Parameters	Description
queue	The URI of the queue to push into

Response Fields	Type	Description
queue	URI	The URI of the queue the message was pushed into
message	URI	The URI of the message that was pushed
content-md5	string	MD5 hash of the request body

PopMessage

Returns a message and deletes it from the queue. If no message can be found, null is returned for the message field.

Query Parameters	Description
queue	The URI of the queue to fetch the message from

Response Fields	Type	Description
queue	URI	The URI of the queue
message	Message	The messages that was dequeued

Common Errors

Invalid Method

Since the msg service takes only POST requests, all other http methods are quit with a 405 error.

Invalid Action

StatusCode: 400 If the action parameter is unknown.

Invalid Request

Most actions require a queue parameter. If it is missing, the msg services responds with a ErrorMessage and a 400 status code.

QueueNotFound

When the specified queue cannot be found, an ErrorMessage and a 404 is returned.

Internal Server Error

If an unexpected error occurs, an ErrorMessage with the text “Internal Server Error” and a 500 status code is returned.

Authorization

Authorization is simply handled via htbasic auth as defined in the HTTP protocol.

Permissions

Like the fs-php service, msg supports policies to fine tune access to actions and/or resources for special users.

All actions are prefixed with msg:: and contain the name listed above, e.g. msg::DescribeQueues, msg::PushMessage. All resource names start with msg: followed by the type and a unique id, e.g. msg:queue:123ac12 or msg:message:123141231. Actions that do no work on a specific resource, use the resource msg:*.

Examples

$accessManager->newPolicy()
->description('Eve may push into the ')
->forUsername('eve')
->permission('msg::PushMessage')
->forResource('msg:queue:bf54e8c38a1dbe21246e268ab3109aff');
$accessManager->newPolicy()
->description('Bob may only check queues and consume messages')
->forUsername('bob')
->permission('msg::Describe*')
->forPermission('msg::PopMessage')
->forResource('msg:*');

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

Docs: Deployer

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

Deploys code. Into folders. From artifacts. Like Crazy. So much wow.

Deployer is a service to deploy static or php websites.

Features

Supports different target sites
Sites can have a different setup
Sites can optionally include a separate configuration tarball
Installation into sibling folder and moving in place for atomic updates via symlink rename (simple blue/green)

Limitations

Currently only supports deployments of artifacts from fs
Currently only supports .tar.gz artifacts
Sites for deployment must be predefined by an admin

Endpoint

The API endpoint is at https://apps.moinz.de/deployer/deploy.php. A valid bearer authorization header is required.

Usage

After installing, have your deployment script publish your artifact as a tarball to fs and then perform a POST request to deploy.php with a site and desired_version parameter.

curl -XPOST https://apps.moinz.de/deployer/deploy.php \
 -d site=help.moinz.de \
 -d desired_version=master-12314556789123

Inside the fs storage, the following path will now be deployed: /artifacts/help.moinz.de/master-12314556789123/help.moinz.de.tar.gz.

Site Configuration

{
 "name": "Moinz.de Blog (production)",
 "path": "/home/zeisss/www/moinz.de/htdocs/blog",
 "artifact": {
 "artifact": "moinz-de-blog-production",
 "artifactBundle": "moinz-de-blog.tar.gz"
 },
 "config": {
 "name": "artifact-name",
 "revision": 42
 }
}

Key	Comment
`name`	Name of the site
`path`	Target site where active app files should be linked to
`artifact.artifact`	Name of the artifact - will be used to find artifacts
`artifact.artifactBundle`	Name of the artifact bundle that should be deployed
`config.name`	Name of the config bundle to unpack ontop of the artifact bundle
`config.revision`	Revision of the config bundle to unpack