Reflecting on API implementation

We're at the point where I get to look back on my decisions for implementing the API and cringe at how badly it was though out in retrospect. Now is my time to do something about it. To get a view of the damage, we can take a look at each end point category and list out all of the handlers that are needed to implement the current implementation.

This gives a quick overview of how much space is being wasted by repetition. One thing that I'm going to be need to be careful of is deciding how I want to separate out this approach. I can try and create modules from the existing end-point without changing anything. Or I can try to reduce the number of end-points as I create the modules. Each of these approaches has their advantages and disadvantageous, but I think either way it's going to be sticky.

Right now I should probably focus on identifying what the problems are and then create a plan of attack after sketching everything out.

For contacts we can split out the route handler into the GET (green) and POST (purple) end points, and then make a quick list of what happens for each route. We find that a lot of the same happens. When we create a business card, we get information about the current user/organization and then sign the business card and return it.

When we add a contact, we take a business card. And then repeat the previous process and send it as a presentation.

For the get contact list and contact tables, these are pretty obvious duplicates. These might have different uses in the front end application, but these differences would be better implemented by adding in a GET parameters to the end point as opposed to having separate end points that are calling the same thing.

In terms of planning out our modules. We end up with something like this. Where we have a Contacts module. That Contacts module is going to interact with Credentials for Verifiable Business cards, and Presentations to send our Verifiable Business Card to another node. Both Credentials and Presentations are going to need access to our Key Material for managing signatures.

Settings and Session aren't grouped, but it makes sense to look at them together. And what we find isn't good. With respect to Session it looks pretty normal for logging in, getting existing session data, and logging out. But them we look at signup which looks out of place in Session.

We would expect life cycle end points to come together. So create, update, and remove should be actions on the same module. In this case when we create a new member, we are either creating a new member for an exiting organization(not implemented), or a new member along with a new organization. So we would expect to see this end point exist with other endpoints with similar functionality.

These end points are currently grouped under Settings for updating a profile (which is really member information), and updating an organization.

When we do our sign up form, what we're actually doing is creating a new organization. And by definition we need a default admin member as a parameter. So what we should really be doing is calling create organization. For modules, what happens is we end up with something like the following.

We have a Session module which has a relationship to be able to read member and organization information on login. The Member and Organization modules need to be able to update the Session module if any changes have been made to information about either of these.

The Member and Organization modules interact with each other in the respect that an admin member needs the ability to update an organization, and an organization needs the ability to create and add members.

Lastly an organization has access to a mnemonic. While members only need access to their respective key pair.

Tray is going to be a little bit of a different representation with my notes. We have three functions.

1. Get count
2. Get documents
3. Get total

These functions are applied to invoices, which should be implied. Invoices can be in draft state or an archived state. So our end point point can include archived=true or draft=true. Or an optional parameter of status=draft/active/archive with active being the implied state, which can be decoratively defined.

I might be jumping too far ahead on this, but it seems like total, count and documents could be grouped as parameters as well to just have one GET /api/tray/ call. Though I'm not sure what I would call that property. So it looks like this might be /api/tray/count, /api/tray/total and /api/tray, since these have different uses in the application.

No module diagram needed for modules for tray. It looks like we only need one Tray module, since all we're doing is select queries from the database.

Going to end this post to avoid going on for too long. In the next post we'll need to look at wallet, trace and invoice for route end-point grouping.