Endpoints

These endpoints provide you with the ability to get certain information from the remote node. In summary, /status provides you a way to check the status and accessibility of the remote. /intro gives you a way to be introduced to the node. Definition of 'being introduced' is to be in sync with a node. In addition, every entity in the network has their own endpoints that return objects of their respective types. Protocol extensions can add their own objects and endpoints with custom behaviour.

All of these endpoints support GET, thus should be accessible via a normal web browser. This is useful for debugging. If you want to connect to your node, simply access https://[ip-address-of-node]:[port]/[protocol-version]/[endpoint]. For more complex queries, you can use web browser extensions that allow you to construct a POST request.

All connections between nodes are force-HTTPS. Any non-encrypted connection between the nodes are forbidden and should result in a 400 Bad request. The nodes should not redirect HTTP queries to HTTPS, the queries should outright fail.

Utility Endpoints

These endpoints provide you utilities. They do not map 1:1 to entities provided therein, but they are tasked with several higher-level tasks such as communicating the status of the node, providing you with an introduction, or bootstrapping off of a node.

• Status
• Node

Status

Endpoint: /status

GET

Status is how you check whether a node is online, and is not too busy for you to connect. If you receive an 200 from a status, the node is online, and will be able to respond to you. If you receive a 429, the remote node is busy, and you might be better served connecting to some other node for the time being.

There is no body to this request.

In a static node, you can satisfy this behaviour by creating an empty "status" file without an extension in the folder that is being served.

Filters

Does not support any filters.

Node

Endpoint: /node

GET

Node endpoint is how you get the data about the node that is available at the address you connected to. This is usually the second step in the process, the first step being /status to check if there is somebody online at the given address.

The body of this request is a node header.

In a static node, you can replicate this behaviour by creating a "node" file without an extension whose contents have information about the node in the folder that is being served.

POST

If the local nodes provides a Node header, the status endpoint responds with the remote node's Node header. The remote will also save the local to its database for possible future connections.

Filters

Does not support any filters.

Entity Endpoints

All of the objects in Mim, but not sub-objects, will have their endpoints. For example, Board is the endpoint where you query and get board objects. Example request and responses can be found here.

• Boards
• Threads
• Posts
• Votes
• Keys
• Addresses
• TrustStates

Entity GET

If you do a GET on any entity endpoint, you will be given the objects of that endpoint in accordance with the standard results policy. This reply will be coming from a cache. See Usage Examples for the syntax of this reply.

[entity]/index

https://1.2.3.4:34821/v0/boards/index

This endpoint provides you with the list of caches for that endpoint. The remote can provide up to 1000 cache links in the responses section.

Each of the cache responses will be approximately 0.15kb. The base schema is 0.7kb. Therefore, with 10000 caches, the maximum size of this response should be below 5mb.

The remote can also provide more than 10000 cache links without violating the protocol, but if the index response size is larger than what would be required for 1000 caches, the local, at its own discretion, can abort. The reason for this is that anything larger than that has a higher likelihood of a denial of service attack.

In the case you abort the caches index for whatever reason, you can access the last cache (detailed below) to access the last cache, which includes its own link, and the link to the prior cache. You can go backwards by following links one by one.

[entity]/cache_[random_cache_id]/0.json

Example: https://1.2.3.4:34821/v0/boards/cache_55a295c39e222e3f94d82d795654a0fea9bc981cd2ae82d7c7b8d4975aa52688/0.json

This returns you the first page of the cache you requested. An example of this response is available at the examples session. Each of these pages have the entities you want to have.

[random_cache_id] is a SHA256 hash of a random string. It has no significance other than being unique and is not stored anywhere.

Example [random_cache_id]: cache_55a295c39e222e3f94d82d795654a0fea9bc981cd2ae82d7c7b8d4975aa52688

[entity]/cache_[random_cache_id]/index/0.json

This is where the index of this cache is. Each of these indexes will be based the cache, and they consist of index of that entire cache.

Addresses do not have a cache, as the index form of Address is itself.

Filters

No endpoint of the entity GET supports any filters.

Entity POST

POST allows you to query the remote node using filters provided in each endpoint, if any.

You will receive the link of the first page of the pagination that includes your answer. This response will be kept alive for 30 minutes from the time of request, so you should be done downloading all the pages before then. See Usage Examples for the syntax of this reply.

Boards

Endpoint: /boards

Provides board objects.

Filters

Supports timestamp, fingerprints and embeds. The embeds are these:

• Threads
• Keys

Threads

Endpoint: /threads

Provides thread objects.

Filters

Supports timestamp, fingerprints and embeds. The embeds are these:

• Posts
• Keys

Posts

Endpoint: /posts

Provides post objects.

Filters

Supports timestamp, fingerprints and embeds. The embeds are these:

• Keys
• Votes

Votes

Endpoint: /votes

Provides vote objects.

Filters

Supports timestamp, fingerprints. Does not support embeds.

Keys

Endpoint: /keys

Provides key objects.

Filters

Supports timestamp, fingerprints. Does not support embeds.

Addressses

Endpoint: /addresses

Provides address objects.

Filters

Supports timestamp, fingerprints. Does not support embeds.

TrustStates

Endpoint: /truststates

Provides trust state objects.

Filters

Supports timestamp, fingerprints and embeds. The embeds are these:

• Keys