JSON Action REST APIs
Discover and use FairCom's REST APIs
This section defines the JSON actions you can POST to the FairCom server. Each action works like a REST call. The HTTPS verb is always POST, and the URI, /api, does not change.
FairCom's APIs use a simplified REST protocol called JSON Action. Each action is a remote procedure call you send as a JSON request and returns as a JSON response. The request and response are always JSON documents sent over HTTPS.
Unlike more complicated REST APIs, your code does everything through JSON. It does not use information in the URI or HTTP header, such as a query string, cookies, authtokens, and so forth. The HTTP verb is always POST, and the endpoint URI is always /api, such as https://127.0.0.1:8443/api.
FairCom's JSON Action APIs support most server features, including creating databases, tables, indexes, inserting/updating/deleting records, querying data using JSON and SQL, sending and receiving MQTT messages, configuring the server, managing accounts and access rights, configuring data connectors to retrieve and push data to devices and software, transforming inserted data automatically, running server-side JavaScript code, managing data change streaming, and so forth.
JSON Action is RESTful
.JSON Action employs the following REST features:
Uniform Interface: JSON Action is RESTful because it uses a standard JSON structure in all requests and responses. JSON Action stores all information in JSON. It stores no information in the HTTP header, such as a URI, query string, cookie, authtokens, and so forth. Thus, JSON Action can work over any protocol, such as WebSocket and MQTT.
Client-Server: JSON Action is RESTful because it follows the client-server pattern, where the client handles the user interface and user state, and the server manages data storage and business logic.
Statelessness: JSON Action is RESTful because it follows the principle of stateless transactions between the client and server, which increases the server's scalability. Like REST, the authentication state is shared between the client and server. A few JSON actions use advanced features, such as database transactions and cursors, that must be stateful across requests.
Cacheability: Static web pages can be safely cached because they change infrequently and provide only one path to change each page. Server APIs cannot be safely cached because they change data rapidly in complex ways and provide multiple paths to change the same data. The creator of REST wrongly assumed that API servers can be cached like web servers. Thus, JSON Actions are intentionally not cacheable and use only the POST verb to enforce the uncacheability of API actions.
Layered System: JSON Action is RESTful because it supports multiple layers between the client and server, including load balancers, proxies, API gateways, and so forth.
Code on Demand (Optional): JSON Actions never send executable code to the client to extend its functionality. This is a potential security issue, and it assumes clients can run JavaScript code. JSON Action is secure and supports all types of application servers, not just JavaScript ones.