|
```json
{
"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",
"biography": "Bio"
}
```
|
String: Birthday in `YYYY-MM-DD` format
String: 2-letter Country Code
String: Gender *(look below)*
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
String: Social media biography with `` as line breaker
</td>
</tr>
</table>
> Standard `gender` values are Male, Female, Lesbian, Gay, Bisexual, Transgender, Queer, Intersexual, Asexual, and Pansexual.
> Clients and servers must code to support others before reporting the problem to me via [email](mailto:islekcaganmert@hereus.net), [GitHub](https://github.com/islekcaganmert/TheProtocols), or [HereUS](https://www.hereus.net/user/islekcaganmert@hereus.net).
> Clients are designed to assume there is no other possible value and unsupported values can cause problems.
> `+` 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.
### 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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password"
}
```
> `current_user_username` must be the username of the user and `current_user_password` must be the password of the user.
Example Response Client Must Expect:
|
```json
{
"birthday": "",
"chamychain_private_key": "",
"chamychain_public_key": "",
"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: ChamyChain Private Key
String: ChamyChain Public Key
String: RSA Private Key
String: RSA Public Key
String: 2-letter Country Code
String: Gender *(look below)*
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")
</td>
</tr>
</table>
> Standard `theme_color` values are red, orange, yellow, green, blue, pink, purple, and blank.
> blank value means for client to not color the UI.
> Standard `gender` values are Male, Female, Lesbian, Gay, Bisexual, Transgender, Queer, Intersexual, Asexual, and Pansexual.
> Clients and servers must code to support others before reporting the problem to me via [email](mailto:islekcaganmert@hereus.net), [GitHub](https://github.com/islekcaganmert/TheProtocols), or [HereUS](https://www.hereus.net/user/islekcaganmert@hereus.net).
> Clients are designed to assume there is no other possible value and unsupported values can cause problems.
> 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.
> 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.
### 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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"key": "",
"data": ""
}
```
> `key` must be in file path format.
> For instance, if client wants to edit biography, key must be `social/biography`.
> If the value placed directly in the root, `key` must be the key directly.
> For instance, if client wants to edit country, key must be `country`.
Client must not expect anything except a status code to learn about is the server was able to save.
### Search
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password"
}
```
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"id": ""
}
```
> `id` must be the id of the post.
Response will be a feed post object.
### Cloud Storage Status
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password"
}
```
Example Response Client Must Expect:
```json
{
"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 as `id`, size of folder contains library data as `library_data`, size of folder contains mails as `mails`, size of folder contains notes as `notes`, size of folder contains reminders as `reminders`, and size of folder contains cold wallet as `token`.
> `total` is total space allocated for the user in byte as integer.
### Notes
To pull all notes from the network, an **HTTPS POST** request to `/protocols/pull_notes` is used.
Example Body Server Must Expect:
```json
{
"current_user_username": "Username",
"current_user_password": "Password"
}
```
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
```json
{
"path": {
"to": {
"note": "Hello, World! "
}
}
}
```
To edit a note, an **HTTPS POST** request to `/protocols/edit_note` is used.
Example Body Server Must Expect:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password"
}
```
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
|
```json
{
"exchange": 1,
"name": "",
"os": {
"arch":"",
"family":"",
"name":"",
"version":""
},
"software": {
"build": 0,
"channel": "",
"developer": "",
"name": "",
"source": "",
"version": ""
},
"version":"3.0"
}
```
|
Float: Exchange Rate Recommended by The Server Software
String: Token Name
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:
```json
{
"public_key": ""
}
```
> Value of `public_key` must be a ChamyChain Public Key.
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:
```json
{
"private_key": "",
"receiver": "",
"amount": 0
}
```
> Value of `private_key` must be the ChamyChain Private Key of sender.
> Value of `receiver` must be the ChamyChain Public Key of receiver.
> Value of `amount` must be the amount of token to transfer as float or integer.
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.
Example Body Server Must Expect:
```json
{
"username": "Username"
}
```
> `username` must be the username of the person we want to learn about.
Example Response Client Must Expect:
|
```json
{
"birthday": "",
"chamychain_public_key": "",
"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: ChamyChain Public Key
String: RSA Public Key
String: 2-letter Country Code
String: Gender *(look below)*
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")
</td>
</tr>
</table>
> 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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password"
}
```
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"email": "username@example.com",
"relation": "",
"smtp": "{}",
"socials": "{}"
}
```
> Value of `smtp` must be string JSON of key value pairs of SMTP addresses of the contact, see contact object for more.
> If contact has no SMTP address, value must be `"{}"`.
> Value of `socials` must be string JSON of key value pairs of social media accounts of the contact, see contact object for more.
> If contact has no social media account, value must be `"{}"`.
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"email": "username@example.com",
"data": ""
}
```
> Value of `data` must be stringified JSON of 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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password"
}
```
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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, clients have nothing to do.
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, these steps must be followed in order:
1. Get AAS Public Domain Key. If you don't know how to, read [How to verify a domain using AAS](https://github.com/islekcaganmert/AAS/src/master/Docs/v3/README.md#verification)
2. **HTTPS POST** request to `/protocols/lowend/add_message_to_server` of remote network.
Example Body Server Must Expect:
```json
{
"add_to": "",
"from": "",
"chat": "",
"body": "",
"domain_key": ""
}
```
> Value of `add_to` must be the username of the sender, not address.
> Value of `from` must be the address of sender.
> Value of `chat` must be the ID of the chat.
> If it is two party chat, it must be set same as `from`.
> Value of `domain_key` must be the AAS Public Domain Key of the sender network.
> **Network must renew the public key as soon as remote verifies it.**
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password"
}
```
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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"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, these steps must be followed in order:
1. Get AAS Public Domain Key. If you don't know how to, read [How to verify a domain using AAS](https://github.com/islekcaganmert/AAS/src/master/Docs/v3/README.md#verification)
2. **HTTPS POST** request to `/protocols/lowend/add_mail_to_server` of remote network.
Example Body Server Must Expect:
```json
{
"add_to": "",
"from": "",
"to": "",
"cc": "",
"body": "",
"subject": "",
"hashtag": "",
"domain_key": ""
}
```
> Value of `add_to` must be the username of the sender, not address.
> Value of `from` must be the address of sender.
> Values of `to` and `cc` must be list of receivers stringified with `;` as deliminator.
> Value of `body` must be in HTML format.
> Hashtag must only contain lowercase, uppercase, and numbers.
> Value of `domain_key` must be the AAS Public Domain Key of the sender network.
> **Network must renew the public key as soon as remote verifies it.**
Sender network must only expect a status code to make sure remote received the mail.
### Library Data
To get library data associated with a package name, an **HTTPS POST** request to `/protocols/pull_library_data` is used.
Example Body Server Must Expect:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"app": "com.example.app"
}
```
> Package name sent as the value of `app` key must be in reverse AAS address format.
Response will be the library 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 dumped as JSON and sent as the value of `data` key accordingly with an **HTTPS POST** request to `/protocols/push_library_data`.
Example Body Server Must Expect:
```json
{
"current_user_username": "Username",
"current_user_password": "Password",
"app": "com.example.app",
"data": "{}"
}
```
Client must not expect anything except a status code to learn about is the server was able to save.
### Security Considerations
### Acknowledgements
| | |