API
This is the API you can use to speak to other nodes. This document gives you a comprehensive understanding of the core concepts of speaking to Mim nodes.
- Methods
- Responses
- Filters
- Minimum Results Policy
- Endpoints
Methods
You can use the two HTTP verbs to be able to communicate with Mim nodes.
GET
When you do a get request to an endpoint of the node, you cannot ask for any specific object. The node will determine what you will receive. The node is can to serve you a truncated result, or a cached one to reduce its own CPU or bandwidth usage, or not do any of thethose things.
POST
When you do a post request, you identify yourself as a Mim node by sending your ID and connection address. This makes you 'join' the network, and other people will start to connect to you, should they want to do so. Doing this on any endpoint (and therefore providing your address for others to connect to) gives you the ability to request specific entities, timestamps, etc.
Responses
The response is be paginated if needed, and in JSON format. Besides the response body, you receive a HTTP status code. There are three codes possible.
HTTP 200 OK
Returned when your request succeeds. The body of this request should be the answer you requested.
HTTP 400 Bad request
You will receive this if your request is malformed, or otherwise unserviceable.
HTTP 404 Not found
Returned when the content you requested isn't available.
If you get a 404 trying to get a new page of the result, you have reached to the end of the content provided by pagination. If the reply you have received had 18 pages, and you are trying to reach the 19th page, you will receive an 204 on the 19th page, because the answer will be empty.
HTTP 405 Method not allowed
You will receive this if you try to do a POST request on a node that does not support it, such as static nodes.
HTTP 429 Too many requests
You can receive this on any endpoint if the remote node becomes too busy.
Filters
For certain endpoints, you can request the result to be filtered (modified) in a certain way. This is what allows you to request a specific object by fingerprint, or keep in sync with incremental updates and else.
Given below are the filters. If an endpoint supports any of those, it will be noted in the documentation for that endpoint.
GET
Cache
All Mim nodes keep (or generate at the point of request) a series of caches to provide other nodes with pre-packaged answers to common queries. This allows nodes to conserve their CPU cycles.
The way you bootstrap (work yourself up to the most up-to-date state) in Mim is that you seek caches of objects from nodes. There are three types of caches.
Every endpoint (board, thread, post, etc.) will have their result cached every day, and retains last 7 copies of these. Each of these days' caches contain the entities that were created or updated that day. When a cache becomes more than 7 days old, the node does no longer have a responsibility to carry that cache, though it might decide to keep a longer duration of past caches if it chooses to do so. These caches are not modified after they are created. Each cache includes a link to the past cache, and if you do a GET on any entity endpoint, you will get the most current cache.
All in all, with the current 7 endpoints, 7 caches each means 49 caches will be kept, plus one weekly cache for index, bringing it to 50 total caches. The first 49 caches are never modified after creation up until the point they are deleted, while the remaining one is updated every day.
The cache filter allows the asking node to specify which day's cache it wants.
POST
Timestamp
If you provide a timestamp, you will receive the objects that were added or updated after the timestamp. Can only be used if the fingerprints filter is not provided.
Fingerprints
If you provide a fingerprint, or an array of fingerprints, you will receive the objects you have requested, so long as the objects are available on the remote node. Can only be used if the timestamp filter is not provided.
Embeds
Certain things can be embedded into endpoint results under certain conditions. For example, in Boards endpoint, you can ask threads and keys for these threads to be embedded. Can either be used with a timestamp or with a fingerprints filter.
By default, these values are only provided as fingerprints on the endpoint. If you embed these values, they will be provided as full objects. These embedded objects are not actually inserted into the main object, rather, they are provided as their own objects and they will count against the standard results policy.
Minimum Results Policy
If an endpoint returns objects, the standard policy of all unfiltered results are that they provide last 7 days' worth of objects ordered by most recent. Minimum response is 10,000 objects or 7 days, whichever is more.
For example, if there were 2400 new or updated (mutable fields changing is considered an update) objects in the last 7 days, the response will still be 10,000 objects, but the remaining 7600 of them will be older than 7 days. The only way you can get an answer that is less than 10,000 objects is that the remote does not have 10,000 objects in its store, in total.
If an endpoint returns embedded objects, the object embeds are provided as their own objects. Embeds are based on certain criteria (i.e. boards endpoint with keys embed will only return keys which are used in the boards that are being provided), so there are no minimum or maximums on the amount of embeds provided.
Index has a special minimum results policy, since it only provides an index, and not the object bodies. At a minimum, index should provide, a week's worth of or 10,000 boards, threads and posts each, and a week's worth of, or 5000 for votes, keys, addresses and truststates each, whichever is more.
The policy provided here is a guidance, and is merely the default settings. These values below should be able to be set by the end user within reasonable limits. There are certain cases where having a lower minimum entity response count makes sense, such as a mobile device.
However, be courteous: if your program does not 'play nice', the other nodes are free to block you out, too. You should be contributing to the network by providing objects when requested in a reasonable quantity and depth.
The spec requires that the nodes communicate how many results they are returning in each type at the beginning of the response.