#809 Haystack 4 Proposal - Op defs

Brian Frank Mon 27 Apr 2020

As we continue to port the Haystack 3 docs over to Haystack 4, I believe we should evaluate how the new def model might apply to the HTTP API operations.  Ops are a great use case where having a first class definition for each operation makes a lot of sense.  

So I'm proposing to create a new feature namespace called "op", and mapping all the standard ops to defs:

op:about
op:formats  // deprecate in favor of op:filetypes
op:ops  // will return op defs themselves
op:read
op:nav
op:pointWrite, op:invokeAction
op.hisRead, op:hisWrite
op:watchSub, op:watchUnsub, op:watchPoll

Also, we need to introduce some new ops to query the def namespace, so I propose the following new ops:

op:libs  // list the library modules in project namespace
op:defs  // list all the defs in the project namespace

Another related topic is the issue of using GET to invoke ops with side effects.  This has the potential to allow CSRF attacks when using cookies for authorization.  So I'd like to standardize how this works.  I propose a new tag noSideEffects which will be applied to the "safe ops" such as about, read, nav.  Only these ops will be permitted to use HTTP GET.  All other ops will be required to use POST.

Stephen Frank Wed 29 Apr 2020

No objections.

Steve Eynon Thu 30 Apr 2020

Sounds good.

Will the op namespace be locked down for only the default ops - or would servers / data providers be able to add their own Ops to it?

Cory Mosiman Fri 1 May 2020

I like the concept of enabling GET requests for certain ops and POST for others.

No objections!

Jonathan Hughes Thu 19 May

I just started experiencing an issue where an old system using haystack 3 stopped working because the other end of the connection got updated to haystack 4. This fails on the ops command which changed. When I tried to find more detail about this I see some documentation issues about how this has been implemented.

  1. Haystack 3 documentation is just gone. No reference to it, no examples of what it used to be for legacy systems, just gone. Seems like a bad idea to just delete all references to a legacy protocol instead of having a 3 and 4 path.
  2. Ops has no example in the API. Every other ops has examples of format but where is the new Haystack 4 format example? Doesn't this seem like a big oversight to not have some indication about what to expect when you send a ops request?

Login or Signup to reply.