Backend Requirements

Description

This document describes the compatibility requirements for file sharing services as of version 1.0.0.

The anonpy is built as a general purpose library, provided the backend in question honors the requirements listed below, i.e. it implements an endpoint for:

• previewing meta data (preview, sometimes also referred to as file info)
• downloading files
• uploading files

Providing an endpoint for inspecting resource meta data is vital to render progress bars in the terminal, and potentially reducing bandwidth on the backend.

Specification

• <url>: the full URL, including its resource identifier
• <resource>: a unique string associated with a file
• <size>: the file size in bytes
• <name>: the file name belonging to the resource, including its file extensions (if available)

The expected input and output is provided by example of their respective curl commands. Generally speaking, the URL of the API takes on the following form:

https://example.com/api/v1/download/<resource>
^       ^      ^    ^               ^
SCHEME  DOMAIN TLD  SUB-DIRECTORY   RESOURCE IDENTIFIER

• The REST API should use an HTTPS scheme
• The sub-directory isn't constrained to any rules, but the relative path must include a resource identifier

The URL used in the examples below are suggestions.

File Upload

curl -X POST -d @<path> https://example.com/api/v1/upload/<resource>

{
  "id": "<resource>",
  "url": "<url>",
  "size": "<size>",
  "name": "<name>"
}

File Download

curl -X GET https://example.com/api/v1/download/<resource>

{
  "id": "<resource>",
  "url": "<url>",
  "size": "<size>",
  "name": "<name>"
}

File Preview

curl -X GET https://example.com/api/v1/preview/<resource>

{
  "id": "<resource>",
  "url": "<url>",
  "size": "<size>",
  "name": "<name>"
}

The preview response should return more information, if possible, though that's not strictly required. Other useful information to include could be:

• mime_type
• checksum
• hash_algorithmn (md5, sha1, sha256, etc.)

Authentication

All endpoints should support basic authentication. Although that's not strictly mandatory, it is recommended to add basic authorization to all requests as well.

curl ... -H "Authorization: Basic <base64>"

Status Health

This library currently doesn't support status health introspection. You can request this feature in a new discussion thread.