TheProtocols Docs

Current Version: 3.1

Test Suite: Not available yet

Implementation report: Not available yet

Author: Cagan Mert ISLEK


Abstract

TheProtocols is a federated protocol for decentralizing super apps by letting people choose a network and a client they want. TheProtocols is designed to provide most functionality a standard user needs in a daily life.

State of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

All interested parties are invited to provide implementation and bug reports and other comments through email, TheProtocols, X, fediverse, or issue tracker. These will be considered in any future versions of this specification.

TheProtocols URL format

This format is used in Resource Pointer object from below.

Name URL
User theprotocols://{username}@{network}
Mail theprotocols://mail:{mailbox}/{id}
Chat theprotocols://chat:{id}
Note theprotocols://note:{path}
Reminder theprotocols://reminder:{list}/{title}
IoT theprotocols://iot:{house}/{room}/{device}
File theprotocols://file:{path}
Event theprotocols://event:YYYY-MM-DD/HH:mm/{index}
Feed Post theprotocols://feed:{id}

theprotocols:// part is not necessary but recommended to avoid TheProtocols cause conflicts with other protocols.

Objects

**Resource Pointer** Used for pointing to any resource on web. 
{
  "title": "Example",
  "url": "https://example.com/index.html",
  "description": "Lorem ipsum dolor sit amet"
}
**Feed Post** A post listed in feed.
`content` is in HTML format and an optional key if this object is in list.
`id` must follow FAT32 filename limitation except space is not allowed.
 
{
  "title": "Post Title",
  "datetime": "YYYY-MM-DD HH:mm",
  "id": "post01",
  "content": "HTML"
}
**Contact** Extensible object to keep extra data about a person.
Addition to the `Relation` and `Socials`, the key-value pairs available in a standard user ID can be added to replace hidden ones.
Value of `Relation` must be `"Self"` if the contact is the current user and empty string if relation is not unique. 
{
  "Relation": "",
  "Socials": [
    "https://example.com/@username"
  ]
}
**Reminder** Standard reminder object.
`deadline` and `last_update_status` must be in "YYYY-MM-DD HH:mm" format.
`last_update_status` is the most recent time the reminder toggled.
`subs` is a list of sub-reminder object. `repeat` must be an interval object. 
{
  "deadline": "",
  "last_update_status": "2024-01-24 11:28",
  "repeat": "",
  "status": true,
  "subs": [],
  "title": "Demo Task"
}
**Sub-Reminder** Sub-reminder object.
`deadline` must be in "YYYY-MM-DD HH:mm" format. 
{
  "deadline": "",
  "status": true,
  "title": "Demo Task"
}
**Chat** Two form object to keep information about two party and multiple party chats.
Two party chats only have `last_index` key, other keys are only for multiple party chats.
`image` must be an URL.
`participants` is a list of TheProtocols addresses of participants. 
{
    "last_index": 0,
    "image": "",
    "title": "",
    "participants": []
}
**Message** An object to keep information about a message.
`date_received` must be in `YYYY-MM-DD HH:mm` format.
`body` must be in Markdown format. 
{
  "from": "",
  "body": "",
  "date_received": ""
}
**Mail** An object to keep information about a mail.
`date_received` must be in `YYYY-MM-DD HH:mm` format.
`body` must be in HTML format.
`sender` must be the address of sender.
`to` and `cc` must be lists of addresses stringified with `;` as deliminator.
`hashtag` must only contain lowercase, uppercase, and numbers. 
{
  "subject": "",
  "date_received": "",
  "sender": "",
  "to": "",
  "cc": "",
  "hashtag": "",
  "body": ""
}
**Event** An event object as part of calendar.
`starts` and `ends` must be in `YYYY-MM-DD HH:mm` format and in UTC timezone.
`country` must be two letter country code.
`travel_time` and values in `alerts` list must have unit suffix: m=minute, h=hour, d=day, w=week, mo=month, y=year
`repeat` must be an interval object. 
{
  "name": "",
  "starts": "",
  "ends": "",
  "location": {
    "name": "",
    "street": 0,
    "no": 0,
    "zipcode": "00000",
    "country": ""
  },
  "alerts": [
    "10m",
    "1h",
    "1d",
    "1w",
    "1mo",
    "1y"
  ],
  "repeat": "",
  "travel_time": "",
  "participants": [
    "john.doe@example.com"
  ],
  "notes": "Markdown",
  "url": "https://example.com/about/event/index.html",
  "attachments": [
    "https://example.com/about/event/photo.png"
  ]
}
**Deleted** Used to inform network to delete a remote object. 
</deleted>

Network Information

To learn about a network, an HTTPS POST request to /protocols/version is used.

Server must not expect any data to be in body for this request.

Example Response Client Must Expect:

{
  "help": "",
  "os": {
    "arch": "",
    "family": "",
    "name": "",
    "version": ""
  },
  "rules": {
    "new_accounts_allowed": true
  },
  "software": {
    "build": 1,
    "channel": "",
    "developer": "",
    "name": "",
    "source": "",
    "version": ""
  },
  "membership_plans": [
    {
      "name": "Free",
      "storage": 0,
    },
    {
      "name": "Plus",
      "storage": 0,
    },
    {
      "name": "Pro",
      "storage": 0,
    },
    {
      "name": "Ultra",
      "storage": 0,
    }
  ],
  "users": [],
  "version": "3.1"
}
String: Username of the account users must contact for help
Dictionary: Information about OS of the server of the network
     String: Architecture of OS *(look below)*
     String: OS Family
     String: OS Name
     String: OS Version

Dictionary: Rule configuration of the network
     Bool: If network accepts new users to create account using TheProtocols

Dictionary: Information about the server software
     Integer: Build number of the server software
     String: Release channel of the server software *(look below)*
     String: TheProtocols address of the developer
     String: Name of the server software
     String: `"Closed"` or URL of the repository of the server software
     String: Version of the server software

Dictionary: Membership Plans

     String: Name of free plan
     Integer: Storage for free plan in bytes


     String: Name of paid plan #1
     Integer: Storage for paid plan #1 in bytes


     String: Name of paid plan #2
     Integer: Storage for paid plan #2 in bytes


     String: Name of paid plan #3
     Integer: Storage for paid plan #3 in bytes


List: List of usernames of the users
String: TheProtocol version server configured

Architecture of OS must be in official format like: x86, x86_64, AArch64

Account Creation & Terms of Service

To create an account on a network these steps must be followed in the order:

  1. HTTPS POST request to /protocols/terms_of_service to view Terms of Service of the network in HTML format. Account creation will assume you accepted.
  2. HTTPS POST request to /protocols/signup with a JSON with these keys:
{
    "birthday": "YYYY-MM-DD",
    "country": "US",
    "gender": "Male",
    "name": "Given Name",
    "password": "Raw Password",
    "phone_number": "+1 000 000 0000",
    "postcode": "54050",
    "timezone": -8,
    "surname": "FAMILY",
    "username": "username"
}
String: Birthday in `YYYY-MM-DD` format
String: 2-letter Country Code
String: Gender
String: Given Name
String: Raw Password of User
String: Phone Number, "+1 000 000 0000" format without spaces
String: Postcode of the user
Integer: Difference of Timezone of User to UTC (ex. -8 is "UTC-08:00")
String: Surname in all uppercase
String: Username with only using ASCII lowercase and `-` symbol

+ symbol can also be used in usernames as alternative accounts of the main account. For instance, user@example.com can use user+untrustedapp@example.com for privacy and prevent spam if the server software supports as TheProtocols specification highly recommends.

Client must not expect anything except a status code to learn about is the server was able to create the account.

Using the Account

After creating an account, next step is logging into it. There is two option for that:

Using Credentials to get a Token: To get a token using credentials, an HTTPS POST request to /protocols/login is used.

Example Body Server Must Expect:

{
  "username": "Username",
  "password": "Password",
  "package": "com.example.app",
  "permissions": [
    "RSA",  // view private RSA key and work with tokens
    "HiddenInformation",  // see information hidden from public
    "Search",  // search objects and index
    "Feed",  // view feed and read posts
    "Contacts",  // list and view contacts
    "ContactsWrite",  // add, modify, and delete contacts
    "Reminders",  // view reminders and lists
    "RemindersWrite",  // add, modify, and delete reminders and lists
    "Chat",  // send and receive messages
    "Mail",  // list, view, move, trash, delete mails
    "MailSend",  // send mails
    "Notes",  // view notes
    "NotesWrite",  // create, edit, and delete notes
    "IoT",  // view states of IoT devices
    "IoT-Full",  // full control on IoT connections
    "ReadFile",  // view filesystem, read files
    "WriteFile",  // write files, create folders, delete any
    "PhotosRead",  // view photos
    "PhotosModify",  // make modifications on photos roll
    "Calendar",  // view calendar
    "Events",  // create, edit, and delete events on calendar
    "ModifyID",  // make modifications on ID
    "InterApp"  // read data and preferences of all apps
  ]
}

username must be the username of the user and password must be the password of the user.

Clients shouldn't expect server to respect all permissions. Server softwares can let users disable some of the permissions.

Example Response Client Must Expect:

{
  "token": ""
}

Using Credentials with Every Request: For compatibility reasons, old method to login (current_user_username and current_user_password with all requests) will stay until 4.0 release.

Continue with no account: You can use some endpoints without account; however experience can be less personalized. To use the Guest account, do not send "cred" argument which means for endpoints to send blank JSON.

Identity of The Current User

To get identity (including personal information and hidden information) of the current user, an HTTPS POST request to /protocols/current_user_info is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Example Response Client Must Expect:

{
  "birthday": "",
  "rsa_private_key": "",
  "rsa_public_key": "",
  "country": "",
  "gender": "",
  "name": "",
  "phone_number": "",
  "plus": false,
  "postcode": "00000",
  "profile_photo": "",
  "settings": {
    "apps": [],
    "plus_until": 20321108,
    "theme_color": "blue"
  },
  "social": {
    "biography": "",
    "emoji": "",
    "story": {
      "content": "",
      "datetime": 202401011200
    }
  },
  "surname": "SURNAME",
  "timezone": -8
}
String: Birthday in `YYYY-MM-DD` format
String: RSA Private Key
String: RSA Public Key
String: 2-letter Country Code
String: Gender
String: Given Name
String: Phone Number, "+1 000 000 0000" format without spaces
Integer: `0` is free plan, `1` is plus, `2` is pro, and `3` is ultra
String: Postcode of the user
String: URL of the profile photo of the user
Dictionary: Settings of user which not owned by an app
     List: List of package names keeping data in library of user
     Integer: When membership of the user ends in YYYYMMDD format
     String: Theme color preference of user

Dictionary: Required keys to create a complete social media profile
     String: Social media biography with `` as line breaker
     String: Emoji to show next to the username
     Dictionary: Story data for social media
          String: HTML Content of Story
          Integer: When story updated in YYYYMMDDHHmm format


String: Surname in all uppercase.
Integer: Difference of Timezone of User to UTC (ex. -8 is "UTC-08:00")

Standard theme_color values are red, orange, yellow, green, blue, pink, purple, and blank. blank value means for client to not color the UI.

If a server software implementor wants to create a feature like email aliases with privacy feature, the server must hide the data while respecting the standards above. For instance, while user_info can hide timezone by replacing with "**" but current_user_info can only hide by replacing with 0 or other standard compatible placeholder.

Servers can modify count of memberships (plus key) available up to 4. That means servers can disable 1, 2, 3, 1 & 2, 1 & 3, 2 & 3, or all. The reason why TheProtocols has standard of memberships is these memberships are considered as TheProtocols Network membership by clients and names must be generated from an integer.

social key can be removed to disable social media integrations. But if server sends this key included, value must follow the standard.

User ID Modifications

To modify a value in user id, HTTPS POST request to /protocols/set_user_data is used.

Networks can be configured to set immutable some of the keys. Client must not expect success everytime.

Example Body Server Must Expect:

{
  "cred": "token",
  "key": "",
  "data": ""
}

key must be in file path format. If the value placed directly in the root, key must be the key directly.

Client must not expect anything except a status code to learn about is the server was able to save.

To search for an object or a website from index of server, an HTTPS POST request to /protocols/search is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "key": ""
}

key is the query string. Network will return every object matching with the key.

Response will be a JSON with a single key value pair. Key is results and contains a list of resource pointer objects matching with the query.

Feed

TheProtocols allows networks to serve a feed. To get the feed, an HTTPS POST request to /protocols/get_feed is used.

Example Body Server Must Expect:

{
  "cred": "token",
}

Response will be a JSON with a single key value pair. Key is feed and contains a list of feed post objects matching with the query.

To get a feed post, an HTTPS POST request to /protocols/get_feed_post is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "id": ""
}

id must be the id of the post.

Response will be a feed post object.

Cloud Storage

To check status of cloud storage allocated for the user, an HTTPS POST request to /protocols/storage_status is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Example Response Client Must Expect:

{
  "total": 0,
  "used": {}
}

used can contain unlimited number of key value pairs to address what uses how much space. Values must be size in byte as integer. Recommended keys to have in used dictionary are size of user id and profile photo as id, size of folder containing application data as library_data, size of folder containing mails as mails, size of folder containing notes as notes, size of folder containing reminders as reminders, size of folder containing contacts as contacts, size of folder containing cloud storage documents, size of folder containing application preferences as preferences, size of folder containing pictures as pictures, size of folder containing IoT data as things, size of folder containing cold wallet as token, and a key value pair per every other feature.

total is total space allocated for the user in byte as integer.

To list files on cloud drive, an HTTPS POST request to /protocols/storage_ls is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "path": "/"  // root is storage folder
}

Client must expect a JSON where key is filename and value is a JSON. Example JSON to expect as a value is:

{
  "type": "empty",
  "size": 0,
  "created": "YYYY-MM-DD HH:mm",
  "edited": "YYYY-MM-DD HH:mm"
}

type is same as what file command echoes after :

To learn about a specific file, put file path into path same as can be done with ls command.

Server must not accept ..

To create a folder, an HTTPS POST request to '/protocols/storage_new_folder' is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "folder": ""
}

folder is in format of /path/to/folder/new_folder

Client must expect no but status code.

To remove something, an HTTPS POST request to '/protocols/storage_delete' is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "path": ""
}

path is in format of /path/to/file

This can be used for both files and folders. However, when applied to folders, it has same effect as rm -rf

Client must expect no but status code.

For read/write operations, access to file under /protocols/storage is used. For example if file path is /path/to/file.txt, /protocols/storage/{username}/path/to/file.txt is the path used with request. There is two possibility. While reading, an HTTPS GET request is used; for writing, HTTPS POST is used.

For reading, leave body empty. For writing, add the content to (over)write there.

While doing these so, add these headers:

Authorization: TheProtocols-Token {your-token-here}`

Photos

To list all photos saved in a day, an HTTPS POST request to /protocols/list_photos is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "date": "YYYY-mm-dd"
}

Example Response Client Must Expect:

{
  "previous": "YYYY-mm-dd",
  "next": "YYYY-mm-dd",
  "list": []
}

previous and next are, respectively to their names, closest days with photos saved in.

list is list of names of the photos from the day.

To get a photo, an HTTPS POST request to /protocols/get_photo is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "filename": "example.png"
}

Example Response Client Must Expect:

{
  "filetype": "PNG image data, 24 x 24, 8-bit/color RGBA, non-interlaced",
  "hex": "...",
  "hash": "...",
  "albums": [],
  "date": "YYYY-mm-dd HH:MM:SS"
}

To save a photo, an HTTPS POST request to /protocols/save_photo is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "filetype": "PNG image data, 24 x 24, 8-bit/color RGBA, non-interlaced",
  "hex": "...",
  "hash": "..."
}

filetype is same as second half after splitting what file command of Unix returns from :

hex is hex of encoded bytes of photo.

hash is hashed bytes of photo, not of hex of it.

albums are list of names of the albums having this photo inside.

Client should not expect anything except status code to know if the network saved.

To move a photo to trash or restore from trash, an HTTPS POST request to /protocols/move_photo_trash is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "filename": "example.png"
}

Client should not expect anything except status code to know if the photo was moved from/to trash successfully.

To list all photos in trash, an HTTPS POST request to /protocols/list_photos_trash is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Client should expect list of names of the photos in trash.

To delete a photo, an HTTPS POST request to /protocols/delete_photo is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "filename": "example.png"
}

Client should not expect anything except status code to know if the photo was deleted successfully.

To list albums, an HTTPS POST request to /protocols/list_albums is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Client should expect list of names of the albums.

To list photos in album, an HTTPS POST request to /protocols/list_photos_album is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "album": "Example"
}

Client should expect list of filenames of the photos in the album.

To create an album, an HTTPS POST request to /protocols/create_album is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "name": "Example"
}

Client should not expect anything except status code to know if the album was created successfully.

To add a photo to an album, an HTTPS POST request to /protocols/add_photo_album is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "album": "Example",
  "name": "example.png"
}

Client should not expect anything except status code to know if the photo was added successfully.

To remove a photo from an album, an HTTPS POST request to /protocols/remove_photo_album is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "album": "Example",
  "name": "example.png"
}

Client should not expect anything except status code to know if the photo was removed successfully.

To delete an album, an HTTPS POST request to /protocols/delete_album is used.

Photos will remain. To remove an album with all inside, all photos must be deleted before deleting an album.

Example Body Server Must Expect:

{
  "cred": "token",
  "name": "Example"
}

Client should not expect anything except status code to know if the album was deleted successfully.

Notes

To pull all notes from the network, an HTTPS POST request to /protocols/pull_notes is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Response client must expect is a plain JSON. If the value of a key is dictionary, the pair is a folder. If the value of a key is string, the pair is a note. For instance, if there notes folder of a user is /Users/user/Notes, and user has a note in /Users/user/Notes/path/to/note.html, response should be

{
  "path": {
    "to": {
      "note": "<p>Hello, World!</p>"
    }
  }
}

To edit a note, an HTTPS POST request to /protocols/edit_note is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "path": "",
  "value": ""
}

path must be the path of the note to edit.

value must be text in HTML format.

Client must not expect anything except a status code to learn about is the server was able to save.

To delete a note, send deleted object as the new value of the note.

Reminders

To pull reminders from the network, an HTTPS POST request to /protocols/get_reminders is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Response client must expect is JSON key value pairs, task list titles as keys and lists of reminder objects as values.

To toggle a reminder, reversing status value, an HTTPS POST request to /protocols/toggle_reminder is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "list": "",
  "id": 0
}

list must be the name of the list.

id must be the index of the reminder in the list. Note that id is not unique and can change, best to pull reminders before editing, toggling, deleting a reminder.

Client must not expect anything except a status code to learn about is the server was able to save.

To edit a reminder, an HTTPS POST request to /protocols/edit_reminder is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "list": "",
  "id": 0,
  "data": ""
}

data must be a reminder object that dumped to JSON.

Client must not expect anything except a status code to learn about is the server was able to save.

To delete a reminder, an HTTPS POST request to /protocols/delete_reminder is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "list": "",
  "id": 0
}

Client must not expect anything except a status code to learn about is the server was able to delete.

To create a new list, an HTTPS POST request to /protocols/create_reminder_list is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "list": ""
}

Value of list must follow FAT32 filename limitations.

Client must not expect anything except a status code to learn about is the server was able to create.

To create a new reminder, an HTTPS POST request to /protocols/create_reminder is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "list": "",
  "title": "",
  "deadline": "",
  "repeat": ""
}

Value of title must be string. deadline must be in "YYYY-MM-DD HH:mm" format. 'repeat` must be an interval object.

Client must not expect anything except a status code to learn about is the server was able to create.

To create a new sub-reminder, an HTTPS POST request to /protocols/create_sub_reminder is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "list": "",
  "reminder": "",
  "title": "",
  "deadline": ""
}

Value of title must be string. deadline must be in "YYYY-MM-DD HH:mm" format.

Client must not expect anything except a status code to learn about is the server was able to create.

Tokens

While interacting with tokens, requests must be done to a relay in the token's network which supports TheProtocols.

To learn about a token, an HTTPS POST request to /protocols/token/about is used.

Server must not expect any data to be in body for this request.

Example Response Client Must Except:

{
  "exchange": 1,
  "name": "",
  "network": "",
  "os": {
    "arch":"",
    "family":"",
    "name":"",
    "version":""
  },
  "software": {
    "build": 0,
    "channel": "",
    "developer": "",
    "name": "",
    "source": "",
    "version": ""
  },
  "version":"3.1"
}
Float: Exchange Rate Recommended by The Server Software
String: Token Name
String: Network of the token *(not all clients to support all networks)*
Dictionary: Server OS Information
     String: Architecture of OS *(in official format)*
     String: OS Family
     String: OS Name
     String: OS Version

Dictionary: Server Software Information
     Integer: Build number of the server software
     String: Release channel of the server software (look below)
     String: TheProtocols address of the developer
     String: Name of the server software
     String: `"Closed"` or URL of the repository of the server software
     String: Version of the server software

String: TheProtocols Version

To check balance of a public key, an HTTPS POST request to /protocols/token/balance is used.

Example Body Server Must Expect:

{
  "address": ""
}

Value of address must be compatible with the target network.

Client must expect a number as plain/text.

To transfer token, an HTTPS POST request to /protocols/token/transfer is used.

Example Body Server Must Expect:

{
  "address": "address1",
  "signature": "",
  "transactions": [
    {"from": "address1", "to": "address2", "amount": 0.05},
    {"from": "address1", "to": "address3", "amount": 0.01}
  ]
}

Value of address, froms, and tos must be compatible with the target network. froms must be same as address

Value of receiver must be Public Key of receiver.

Value of amounts must be a positive float.

To generate signature, stringify same JSON without signature key in this order of keys and generate signature using the algorithm target network uses.

Client must not expect anything except a status code to learn about is the server was able to transfer.

Identity of Others in Federalized Web

To get identity (excluding personal information, hidden information is censored) of others in federalized web, an HTTPS POST request to /protocols/user_info is used.

For this time, unlikely to other requests, we must make the request to the network of the person we want to learn about. DO SEND NEITHER YOUR TOKEN NOR YOUR CREDENTIALS!

Example Body Server Must Expect:

{
  "username": "Username"
}

username must be the username of the person we want to learn about.

Example Response Client Must Expect:

{
  "birthday": "",
  "rsa_public_key": "",
  "country": "",
  "gender": "",
  "name": "",
  "phone_number": "",
  "plus": false,
  "postcode": "00000",
  "profile_photo": "",
  "social": {
    "biography": "",
    "emoji": "",
    "story": {
      "content": "",
      "datetime": 202401011200
    }
  },
  "surname": "SURNAME",
  "timezone": -8
}
String: Birthday in `YYYY-MM-DD` format
String: RSA Public Key
String: 2-letter Country Code
String: Gender
String: Given Name
String: Phone Number, "+1 000 000 0000" format without spaces
Integer: `0` is free plan, `1` is plus, `2` is pro, and `3` is ultra
String: Postcode of the user
String: URL of the profile photo of the user
Dictionary: Required keys to create a complete social media profile
     String: Social media biography with `` as line breaker
     String: Emoji to show next to the username
     Dictionary: Story data for social media
          String: HTML Content of Story
          Integer: When story updated in YYYYMMDDHHmm format


String: Surname in all uppercase.
Integer: Difference of Timezone of User to UTC (ex. -8 is "UTC-08:00")

If a user wants to hide information or a network configured to not collect the data, value must contain censored version of the data. To censor data, replace value with multiple * symbol to mimic length of the original value or any value following standard.

Servers can modify count of memberships (plus key) available up to 4. That means servers can disable 1, 2, 3, 1 & 2, 1 & 3, 2 & 3, or all. The reason why TheProtocols has standard of memberships is these memberships are considered as TheProtocols Network membership by clients and names must be generated from an integer. Extraction of membership plan names from Network Info is planned.

social key can be removed to disable social media integrations. But if server sends this key included, value must follow the standard.

Contacts

Since some value can be hidden from public identity, this can block some functionality of clients. To solve this problem TheProtocols has contacts feature enabling users to fill hidden information of the people they know, changes only visible to them.

To get contacts, an HTTPS POST request to /protocols/list_contacts is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Response will be the JSON with TheProtocols address of the contact as key and contact object as value.

To add someone as contact, an HTTPS POST request to /protocols/add_contact is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "email": "username@example.com",
  "relation": "",
  "socials": []
}

Value of socials must be list of links of social media accounts of the contact, see contact object for more.

Client must not expect anything except a status code to learn about is the server was able to add.

To edit information of a contact, an HTTPS POST request to /protocols/edit_contact is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "email": "username@example.com",
  "data": { ... }
}

Value of data must be a contact object.

Client must not expect anything except a status code to learn about is the server was able to save.

To delete a contact, deleted object must be set to contact data using the same request configuration as editing contact.

Messages (API)

To list chats and get information about chats, an HTTPS POST request to /protocols/list_chats is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Response will be dictionaries, chat id as key and chat object as value.

last_index is the index of the last message in a chat. That means a for loop from 0 to last_index can be used to get all messages. To get a message, an HTTPS POST request to /protocols/get_message is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "chat": "",
  "id": 0
}

Response will be a message object.

To send message, an HTTPS POST to /protocols/send_message is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "chat": "",
  "body": ""
}

body must be in Markdown format.

Client must not expect anything except a status code to learn about is the server was able to save.

To create a chat group, send message with "/" as chat and a new stringified chat object as body.

Messages (Federation)

This requests must be done between networks.

To send a message to a chat, message must be added to the chat in every user's data in the group because TheProtocols assumes messages people receive are in the disk space allocated to the user and there is not a single pool of messages. This means if there is two person in a chat from a different network than the current user, even these two are from same network as each, message must be sent to them separately. Just like sending emails.

To request from a network to add a message to a user's data, an HTTPS POST request to /protocols/lowend/add_message_to_server of remote network is used.

Example Body Server Must Expect:

{
  "add_to": "",
  "encrypted_object": "",
  "signature": ""
}

Value of add_to must be the username of the sender, not address.

encrypted_object is stringified message object encrypted with RSA public key of receiver. Padding is MGF1 and with SHA512. Hash algorithm is also SHA512. Label is none.

signature is generated using RSA private key of sender. To validate successfully, decrypted object must be tested before JSONified back without any change in sort. Padding is MGF1 and with SHA512. Hash algorithm is also SHA512.

Value of from in encrypted object must be the address of sender.

Value of chat in encrypted object must be the ID of the chat. If it is two party chat, it must be set same as from.

Sender network must only expect a status code to make sure remote received the message.

Mail (API)

To list mailboxes, an HTTPS POST request to /protocols/list_mailboxes is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Response will be a dictionary, mailbox name as key and index for most recent mail as value.

Every network must have these mailboxes available for everyone as standard: Primary, Promotions, Social, Spam, Sent, Archive, Trash. Also if a server software has a special process on mails, it can provide more default mailboxes. Users can create new mailboxes by moving a mail to a mailbox not exist. Continue reading to learn how to move a mail.

To get a mail, an HTTPS POST request to /protocols/get_mail is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "mailbox": "",
  "id": 0
}

id is index of mail in the mailbox.

Client must expect a mail object.

To move a mail, an HTTPS POST request to /protocols/move_mail is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "mailbox": "",
  "mail": 0,
  "move_to": ""
}

mail is index of mail in the mailbox.

This will move the mail from mailbox to move_to.

Client must not expect anything except a status code to learn about is the server was able to move.

To delete a mail permanently, move it to -.

To send a mail, an HTTPS POST request to /protocols/send_mail is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "body": "",
  "to": "",
  "cc": "",
  "bcc": "",
  "hashtag": "",
  "subject": ""
}

Values must follow same standards as a mail object except values of to and cc must be stringified with ; as deliminator.

Client must only expect a status code to make sure mail sent successfully.

Mail (Federation)

This requests must be done between networks, clients have nothing to do.

A mail must be sent to everyone added in to, cc, and bcc.

To request from a network to add a mail to a user's inbox, an HTTPS POST request to /protocols/lowend/add_mail_to_server of remote network is used.

Example Body Remote Server Must Expect:

{
  "add_to": "",
  "encrypted_object": "",
  "signature": ""
}

Value of add_to must be the username of the sender, not address.

encrypted_object is stringified mail object encrypted with RSA public key of receiver. Padding is MGF1 and with SHA512. Hash algorithm is also SHA512. Label is none.

signature is generated using RSA private key of sender. To validate successfully, decrypted object must be tested before JSONified back without any change in sort. Padding is MGF1 and with SHA512. Hash algorithm is also SHA512.

Value of from in encrypted object must be the address of sender.

Values of to and cc in encrypted object must be list of receivers.

Value of body in encrypted object must be in HTML format.

Hashtag must only contain lowercase, uppercase, and numbers.

Sender network must only expect a status code to make sure remote received the mail.

Application Information

To identify packages, an HTTPS GET request to /.well-known/app_info.json of domain which is the reverse of package name must be sent.

An example app_info.json

{
  "name": "",
  "icon": "",
  "description": "",
  "latest_version": "",
  "latest_build_number": 0,
  "preferences": {
    "Switch": true,
    "Textbox": "",
    "Slider": 50,
    "Select": {"selected": "Default", "all": ["Default", "Light", "Dark"]}
  }
}

preferences contains default preferences of the application.

Application Data

To get application data associated with a package name, an HTTPS POST request to /protocols/pull_library_data is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "app": "com.example.app"
}

Package name sent as the value of app key must be in reverse domain format.

Response will be the application data as JSON. If there is no data associated with the package name, blank JSON ({}) will be returned.

To push new data, data must be sent as the value of data key accordingly with an HTTPS POST request to /protocols/push_library_data.

Example Body Server Must Expect:

{
  "cred": "token",
  "app": "com.example.app",
  "data": {}
}

Client must not expect anything except a status code to learn about is the server was able to save.

Application Preferences

To get preferences of an application, an HTTPS POST request to /protocols/pull_app_preferences is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "app": "com.example.app"
}

Package name sent as the value of app key must be in reverse domain format.

Response will be the app preferences as JSON. If there is no data associated with the package name, blank JSON ({}) will be returned.

To push new data, data must be sent as the value of data key accordingly with an HTTPS POST request to /protocols/push_app_preferences.

Example Body Server Must Expect:

{
  "cred": "token",
  "app": "com.example.app",
  "data": {}
}

Client must not expect anything except a status code to learn about is the server was able to save.

Calendar

To list all events between two time, an HTTPS POST request to /protocols/list_events is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "after": "YYYY-MM-DD HH:mm",
  "before": "YYYY-MM-DD HH:mm"
}

Response client must expect is JSON key value pairs, event IDs as keys and event objects as values accordingly.

To get an event, an HTTPS POST request to /protocols/get_event is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "id": "event_id"
}

Response client must expect is the event object which is queried.

To create an event, an HTTPS POST request to /protocols/create_event is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "object": event_object
}

To remove an event, send deleted in object

Response client must not expect anything than status code if server saved changes.

To overwrite an event, an HTTPS POST request to /protocols/set_event is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "id": "event_id",
  "object": event_object
}

To delete an event, send deleted in object

Response client must not expect anything than status code if server saved changes.

IoT

To list all rooms in the house, an HTTPS POST request to /protocols/list_rooms is used.

Example Body Server Must Expect:

{
  "cred": "token"
}

Response should be a list of room names.

To list all things in a room, an HTTPS POST request to /protocols/list_things is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "room": "room"
}

Response should be a list of thing names.

No thing can be named same in a same house.

To get status of a thing, an HTTPS POST request to /protocols/get_thing is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "thing": "Thing's Name"
}

Then network will proxy JSON to smart hub's /protocols/lowend/get_thing endpoint without creds after signing with user's RSA key. Signature will be added to JSON as the value of signature. Also, owner email must be added as user in username@network format.

Example Body Hub Must Expect:

{
  "datetime": "YYYY-mm-dd HH:MM:SS",
  "user": "username@example.com",
  "signature": ""
}

signature must be generated using all content above without signature key.

Network will receive latest status as JSON-LD from thing as the response and return (to client) as received (from hub)

To set status of a thing, an HTTPS POST request to /protocols/set_thing is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "thing": "Thing's Name",
  "modified": {}
}

modified includes every key-value pair modified from thing object. It is not necessary to send whole object back.

Then network will proxy JSON to smart hub's /protocols/lowend/set_thing endpoint without creds after signing with user's RSA key. Signature will be added to JSON as the value of signature. Also, owner email must be added as user in username@network format.

Example Body Hub Must Expect:

{
  "datetime": "YYYY-mm-dd HH:MM:SS",
  "modified": {},
  "user": "username@example.com",
  "signature": ""
}

signature must be generated using all content above without signature key.

Network will receive latest status from thing as the response and return status code 200 to client if all applied successfully.

To create a room, an HTTPS POST request to /protocols/create_room is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "name": "New Room"
}

Client should not expect any than a status code.

To delete a room and unregister all things in it, an HTTPS POST request to /protocols/delete_room is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "name": "To Be Deleted Room"
}

Client should not expect any than a status code.

To unregister a thing, an HTTPS POST request to /protocols/unregister_thing is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "thing": "To Be Deleted Thing"
}

Client should not expect any than a status code.

To register a thing, an HTTPS POST request to /protocols/register_thing is used.

Example Body Server Must Expect:

{
  "cred": "token",
  "room": "Room",
  "name": "New Thing",
  "url": "users-new-device.example-tunnel-from-manufacturer.com"
}

It is highly suggested to networks to try to fetch device status before registering. This will prevent from future errors to be raised by a mis-coded software in the flow.

As can be seen in example, it is highly recommended for users to set their devices over a tunnel instead of leaving ports open from their home router to avoid hack. It would be more user-friendly if hubs have a tunnel software preloaded. However, clients must never expect all users to use a commercial tunnels.

Client should not expect any than a status code.