Interfaces

Pre-requisite Readings {hide}

Types of Application Interfaces

SDK applications generally have a Command-Line Interface (CLI) and REST Interface to support interactions with a full-node. The SDK is opinionated about how to create these two interfaces; all modules specify Cobra commands and register routes using Gorilla Mux routers. The CLI and REST Interface are conventionally defined in the application ./app/cmd/cli folder.

Module vs Application Interfaces

The process of creating an application interface is distinct from creating a module interface, though the two are closely intertwined. As expected, module interfaces handle the bulk of the underlying logic, defining ways for end-users to create messages and queries to the subset of application state within their scope. On the other hand, application interfaces aggregate module-level interfaces in order to route messages and queries to the appropriate modules. Application interfaces also handle root-level responsibilities such as signing and broadcasting transactions that wrap messages.

Module Developer Responsibilities

With regards to interfaces, module developers need to include the following definitions:

  • CLI commands: Specifically, Transaction commands and Query commands. These are commands that users will invoke when interacting with the application to create transactions and queries. For example, if an application enables sending coins through the auth module, users will create tx auth send transactions.
  • Request Handlers: Also categorized into Transaction and Query requests. Transactions will require HTTP Request Types in addition to Request Handlers in order to encapsulate all of the user's options (e.g. gas prices).
  • REST Routes: Given a router, the module interface registers paths with the aforementioned Request Handlers for each type of request.

Module interfaces are designed to be generic. Both commands and request types include required user input (through flags or request body) which are different for each application. This section of documents will only detail application interfaces; to read about how to build module interfaces, click here.

Application Developer Responsibilities

With regards to interfaces, application developers need to include:

  • CLI Root Command: The root command adds subcommands to include all of the functionality for the application, mainly module transaction and query commands from the application's module(s).
  • App Configurations: All application-specific values are the responsibility of the application developer, including the codec used to marshal requests before relaying them to a node.
  • User Configurations: Some values are specific to the user, such as the user's address and which node they are connected to. The CLI has a configurations function to set these values.
  • RegisterRoutes Function: Routes must be registered and passed to an instantiated REST server so that it knows how to route requests for this particular application.

Next {hide}

Read about the Lifecycle of a Query {hide}