2017-04-18 Meeting note


7am PDT


Optional dial in:
Dial in: 401-283-5773
PIN: 66343

  • note the changed dial in number and pin



  • Review options w/ adding features v sem ver
  • Review Malawi Average Consumption extension proposal

Discussion items

  • Review agenda
25mReview options with semver and Reference DataJosh 
30mReview Malawi extension for average consumptionSebastian Brudziński

In a Reference Data system the major semantic version always goes up...  now you know what's up


Reference Data was developed rapidly and is used by many other services.  As those Services need to get data from Reference Data, there are more custom search endpoints for finding the right data as well as needs for the data to be returned paginated.


There has been some concern expressed that every release of Reference Data has been new major version, and this doesn't feel right.


By Semantic Versioning, releasing a new major version designates to consumers of the public API that some part of it changed in a breaking way.  For Reference Data this means the RESTful API.  The most recent releases, v5 and v4, included:

  • structural changes in the commodity model (unfortunately not all changes made it into the v4 release)
  • users search endpoint was made paginated
  • the Facility resource now supports the extension mechanism ExtraData, which pushes the Facility search endpoint from a GET operation to a POST operation

Of these, the structural change to the commodity model is the one that feels like it warrants the major version change - most everything uses the commodity model, and we've known we've wanted to make this change since before v3 was released, we just haven't gotten all of the change done in one major release, in part due to a quicker release cycle of Ref Distro.

Pagination and support for extra data however feel like we have some options.


#1, Do the work, break the contract, and release as a major version

This option is the simplest for the component - we simply change the contract for the search endpoint and/or the pagination and we release the next major version of Reference Data. 

Makes just the change/work that's neededBreaks the contract, so the semantic version has to be increased, and all consumers have to do work to account for the change

#2, Do the work, don't break the contract, and release a minor version

Both of the reason's we've identified (extra data and pagination) involve a breaking change to the search endpoint of a Resource.  It follows that a new Search endpoint could be introduced that supports pagination as well as extra data's POST, while the old one is marked as deprecated yet retained.

Makes just the change/work that's neededConsumers will eventually have to do the work when the deprecated operations are removed
Doesn't break the contract, consumers still workWill have to maintain both endpoints while they both exist (fixing bugs, refactor?)

We would think that we would phase out the deprecated operation in the next MAJOR release, though a set amount of minimum support time (e.g. 6 months) might be preferable.

#3, Do all the work NOW - and release the new major (uber) version

As it's name implies, it means that we should paginate all the Search endpoints, and add ExtraData to all of the current (about 22) Resources of Reference Data service.

Big bang - everything is fixed (we could more things)Breaks the contract, so the semantic version has to be increased, and all consumers have to do work to account for the change - to all the resources
Ref Data service would be more consistent - cognitive loadResource intensive - this scope of work may require a team (small) to go through and make all the changes.  Also all other components may need more human resources

We may do work that's un-needed.  Maybe supply lines will never need extra data.  Stock adjustment reasons may go away, replaced with stock management service.

We may not really prevent the major version from being incremented rapidly.

Moving from GET to POST for search, and implementing pagination for search, could reduce people resources for making reference data better (maybe half the work).  Consumer LOE would stay the same.

Malawi - Extension for average consumption

Average Consumption calculation - extension analysis

Some question about the LineItemFieldsCalculator calculations and the delegating class - feels weird to have both

How does the data get back to the UI?

  • Is it an extension to the calculation class?  Or an extension to getting previous requisitions?  Or both?
  • If it's just the previous requisitions, then if the configuration is the previous N years

Next steps:

  • check to see if previous requisition approach (returning N in DTO) is feasible
  • mature the document (specific ext approach, actions and timeline, containers and packaging) - ping technical forum
  • tech comm to review future draft

Action items

  • Josh Zamor to throw up voting for Reference Data poll of the forum (everyone votes by wed/thur)
  • Sebastian Brudziński to continue maturing Malawi Ext. Proposal for Average Consumption.  Post to technical forum for intermediate feedback
  • Sebastian Brudziński to remind technical committee to discuss new draft document at next committee call (May 2nd)