API documentation refinement

In the previous post, we started to take another look at our documentation to figure out how we would break down our modules. We left off at invoices, so that's where we'll continue.

With invoices, it's harder to jump right into modules as we have a lot of end-points. The first step is to look at these and sort them out. Effectively we have five categories.

The first category is draft-related. We can create, update and delete a draft. This will only make changes on the node of the person creating the draft, and does not need to make requests to any other nodes.

From there we have four seller status update end-points and four buyer status update end points. These are all server calls that will change the state of the invoice, and requires messages to be exchanged between different nodes. Effectively these could all be grouped into one call that manages state, and we provide the state change as a parameter.

From there we have six GET functions for getting a document, or information about the buyer and seller. In general we would only want to have one GET function for any given document. And getting information about the buyer or the seller is something that could happen on the client side. And it's not something that requires a server-call, but I would need to go back and see how it is being used in the application.

The next set of end-points we have is the wallet category. There isn't too much to change in this set of end-points, as it's a list of fairly unique GET functions.

The first and obvious change to make here is to get rid of the ipfs integration. Our goal is to make the application simplier and smaller, so this is an obvious one to cut out and remove to reduce the number of moving parts.

And the next issue we have with this section is the name, "wallet". Normally I would be fine with that term for this section, as these end-points deal with how many funds we have for a specific currency. The problem with the term "wallet" is that everything is a wallet.

Mnemonics and private keys can be stored in a wallet. Credentials could be considered part of a wallet. So it's hard to say in a system like Private Invoice where the wallet starts and ends.

Ideally we might be more specific and call this "funds", "crypto", or "ETH" as far as being specific about the functionality and avoid using a generic umbrella term.