API WIP & Schema Changes 2021-06-11

Luke and I have continued refining and updating the API in our working spreadsheet.

It’s been a few late nights but the results are satisfying. I love the almost fractal nature of the this kind of iteration: months ago, we started adding and removing big trunks of endpoints, then as these firmed up the trunks stayed set and limbs started coming and going, and then those held together while the branches shifted and moved. Now we’re able to walk through the API manually and identify critical issues and missed opportunities.

The changes:

  • Bigger structure changes
    • Having metadata-indexing endpoints was causing some confusion. Some developers thought that these would be their main way to identify what data could be acted on, but this should be stored locally in your database; you should not have to ask the respondent what your plans or slices are, since these are all part of the plan documents the software agreed to. It seemed like a dangerous duplication of methods that would lead to spaghetti implementation
      • /v1/slices (now only accessible by specific slice UUID via /v1/slices/[uuid])
      • /v1/plans (UUID as well, /v1/plans/[uuid]
    • The XSD schema now allows the Secondary element to be empty to support plan invoke action (see below)
  • Added statuses for plans in the db schema
    • Invoked – plan has been newly created and contains only Primary information
    • Proposed – plan has been proposed
    • Approved – plan is ready to use for synchronization
    • On Hold – plan has been “frozen” and can’t be used for synchronization, but could be re-activated if both actors agree
    • Rejected – plan has been rejected by one of the partners and can’t be used for synchronization
  • Added “status_message” free text field to the db schema to allow storing a simple message about the plan’s status that can be relayed in the plan metadata
  • Added / modified the process for bootstrapping, maintaining, and proposing a new plan
    • One of the biggest hangups has been the “chicken and egg” precedence for new plans. How do partners exchange their core details when they haven’t yet established a plan? This is our new method:
      1. The respondent gives the initiator (out of band, via email, phone, or other “human” channel) a basic server address, username, and password, to use with /v1/login
      2. Initiator logs in there with a null plan in the body. Their access, returned in the JWT, will be limited to the /v1/login and /v1/plans/* endpoints
      3. Initiator connects to /v1/plans/invoke to get a new stub plan with a new UUID. This UUID should not change until the plan is offered as a proposal.
        1. If the initiator is the primary:
          1. Initiator POSTs their primary node information as a plan with no Secondary or Common elements
          2. Respondent fills in the Secondary and Communal elements, then places the plan (which should not change UUIDs at this point) in the Proposals area. Now the UUID should be considered “frozen” and further changes will require a new UUID
          3. Respondent reviews the plan and either approves, rejects, or places it on hold
          4. Initiator logs in and checks the plan status again after some time and, if approved, can begin synchronization. If rejected, the reason is available in the metadata, and they can resolve by reaching out admin-to-admin or by creating a new plan with a new UUID (at this point, I don’t think it’s necessary to do this through the /v1/plans/invoke interface, but perhaps it should be? Up for debate, and something we’ll discuss today on our technical call), based on the previous plan, and propose again
        2. If a secondary:
          1. Initiator will GET a stub plan with no Secondary or Common elements
          2. They will fill in their information (preserving the UUID as above) in the Secondary and Communal elements, then POST this proposed plan to /v1/proposals/new. The UUID is now frozen.
          3. Respondent reviews the plan as above
          4. Initiator logs in again as above
    • Plans can now be frozen using /v1/plans/[uuid]/hold, which will place the plan status into “On Hold”

I think this about covers the main changes. Luke has begun integrating these into his test server and inspector tool. Please feel free to bring up any thoughts via our Contact & Connect page!