I’m wrapping an existing api, and exposing a user interface that’s inspired by Sente’s. Users send messages that contain an event-id (which could be thought of as the function/command) and a map of named arguments, and asynchronously receive responses.
For example, the user would send the following message to the connection object:
[:my-lib.request/market-data {:stock {:symbol "AAPL"} :live? true :request-id 42}]
or
[:my-lib.request/historical-data {:stock {:symbol "AAPL" }
:start #inst "2018-03-07T04:20:02.318-00:00"
:days 30 :request-id 52}]
I’m just wondering which keywords should be namespaced here?
All these events and arguments will be fully spec’ed.
I feel it’s somewhat easy to decide that the first item in the vector, the event-id, should be a namespaced keyword, because it’s sort of like calling a function but since it might go over the wire it needs to be referred to in a global context (and also because I’m just ripping off this requirement from sente). But what about the rest, the named “arguments” map? Should those be namespaced?
There are a large number of types of functions besides the two shown with a wide range of arguments. Some of the arguments are common among multiple of the calls, like :stock
here. Overall there are a ton of things to be named by keywords.
Does the fact that they’re wrapped in a vector which describes the intent of the command with the event-id provide enough context to not require namespaced keys?
If I do namespace the keys, what namespace do I use? Do I use “nest” them under the event-id
like so:
:my-lib.request.market-data/stock
,:my-lib.request.market-data/live?
But then shouldn’t the common arguments across the api be denoted by the same keyword if they refer to the same type of thing (ie, the same spec)? The stock “type” appears across many calls, so should I just always denote it by :my-lib/stock
but then fall back on the :my-lib.request.market-data/live?
for non recurring arg names?
Do I chop off the first few segments and just go with market-data/contract
and :market-data/live?
Are any of these questions themselves a possible hint that I’m designing this api all wrong?
I’ve been agonizing over these decisions for a few days and not getting anywhere. Would love to hear other people’s thoughts!