API Design considerations

[jhbertra]

Recently, I've been doing a bit of reworking of the new Marlowe Run Server API, and thought it would be good to discuss some of the considerations here. Here are a few of the ideas I would like to propose we adopt. Most of them are focused on minimizing risk and friction due to changes:

• APIs should be versioned. E.g. I'm in the process of adding a /v1 after api/wallets so that we can work with a versioned wallets API. That way, when we create a breaking change to the API, which we undoubtedly will, we can simply create a new v2 version of the API without having to rework the existing one. Another benefit of this is that we can make POST /wallets/centralized-testnet/restore simply be POST/wallets/v1, because restoring from a mnemonic generated by the WBE is the only means of "posting" a wallet in v1 of the API,
• APIs should not expose Domain types. I'm in the process of adding a DTO layer to the server. All the APIs should consume and produce trivially serializable types that are solely designed for the purpose of data transfer (Data Transfer Objects). This will make the API schemas cleaner, and will minimize the shared code between front end and back end. This will make dependency upgrades much simpler in the future, because there won't be the risk that changes in the plutus-apps repo will cause our generated PureScript to break. This is also a lot more in alignment with the "share nothing" philosophy that is crucial to stability in a multi-repo scenario.
• To this end, I've split the Server modules into two halves:
  • Marlowe.Run.xxx this module defines the core business logic of the application. The functions it exposes accept full domain types and return full domain types. They also operate without the assumption that they are in an HTTP server environment. This gives us the flexibility of plugging them into other runtime configurations, such as the Marlowe CLI.
  • Marlowe.Run.xxx.Server this module binds the functionality exposed by Marlowe.Run.xxx to the API defined by Marlowe.Run.xxx.API. Its jobs are to:
    • Translate between DTOs (in requests and responses) and domain models (used by core business logic).
    • Translate domain errors (produced by business logic) to HTTP error responses.