littlebits / cloud-client-api-http Goto Github PK

Perhaps we should use bluebird promises

Originally detected in https://github.com/littlebitselectronics/cloud-server-api-stream/issues/23.

Add support for the new V3 API endpoint that allows for GETing a stream of input amplitude of a device.

This endpoint also supports https://github.com/littlebits/stream-sift features but because the endpoint is a GET the pattern spec must be sent as a urlEncoded value. This library should make this arcane and asinine process transparent to the user.

Also, what will the stream API we use be? Kefir? Custom?

Still missing from the api but of course we need it.

Our v3 API supports complex subscription models, does the client library?

We need to expose the device model updating, probably like this:

api_http.device_update

Need a simple script with public URI that people of all skill levels can include in html pages and immediately use. Most likely will register a global object called littleBitsAPI or similar, a simple example usage would be such as littlebits/cloud-api-lessons#4

• Committed dist
• Committed dist-min
• littleBits cdn hosting of dist + dist-min

There is no reason why an oauth error should be anything but an IO error from library users' point-of-view.

The current solution to options arguments is lame. Firstly we don't base our key names on those in the HTTP API spec because that goes against JS naming conventions (= more unimportant details for developers to remember), secondly, we don't standardize the HTTP API spec key names to camelCase because of the terrible results entailed: subscriberId, durationMs, etc.

So we lose either way: unique names to learn, difficult-to-read names.

However there's a third way: support both. This has several benefits:

• developers insisting on camelCase can do so (ugly, but their choice)
• developers favouring readability can use snake_case (non-standard style, but their choice)
• important: a _pattern_ is defined for converting HTTP API options key names, _nothing unique to learn_
• important: a _pattern_ lends itself to _automation_ AKA algorithm. so we can do away with our manual labour e.g. here: https://github.com/littlebits/cloud-client-api-http/blob/master/lib/customizations.js#L12-L14
• @stresslimit should be happy, and I like making @stresslimit happy

Remove library confusion. We're not tailoring to python developers. And we're not going to single-handedly change the JavaScript industry.

The following sketches the core necessary actions and their types.

-- Devices Actions

devicesGet :: AccessToken -> Promise (List Device)

-- Device Actions

devicePost     :: AccessToken -> DeviceSpec -> Promise Device
deviceSettings :: AccessToken -> DeviceID -> SettingsSpec -> Promise Device
deviceGet      :: AccessToken -> DeviceID -> Promise Device
deviceDelete   :: AccessToken -> DeviceID -> Promise Device

-- Device Input Actions

deviceInputGet :: AccessToken -> DeviceID -> ReadSemantics -> Promise InputEvent

-- Device Output Actions

deviceOutputPost :: AccessToken -> DeviceID -> Promise ()

-- Relation Actions

relationPost         :: AccessToken -> RelationSpec -> Promise Relation
relationGet          :: AccessToken -> EdgeIdent -> Promise Relation
relationGetSubjects  :: AccessToken -> VertexID -> Promise (List Relation)
relationGetObservers :: AccessToken -> VertexID -> Promise (List Relation)
relationDelete       :: AccessToken -> EdgeIdent -> Promise Relation

Sugar for AccessToken

There should be an easy way for the user to get an API that has the first argument AccessToken applied. For example the following could return whole API with AccessToken partially applied to each action:

littleBitsCloud
  .withUser('83hs026fbn2pqw=27qbs91571k')
  // deviceSettings :: DeviceID -> SettingsSpec -> Promise Device
  // deviceGet      :: DeviceID -> Promise Device
  // etc.

Sugar for DeviceID

There should be an easy way for the user to get an API to work with a specific device wherein the second argument DeviceID is applied. For example:

littleBitsCloud
  .withUser('83hs026fbn2pqw=27qbs91571k')
  .withDevice('71d1hoa610')
  // deviceSettings :: SettingsSpec -> Promise Device
  // deviceGet      :: Promise Device
  // etc.

The returned API function names should have aliases that drop the device prefix given that it is redundant in this chaining context. So for example these two would be the same:

littleBitsCloud
  .withUser('83hs026fbn2pqw=27qbs91571k')
  .withDevice('71d1hoa610')
  .deviceSettings({ input_interval_ms: 50 })
  // ...

littleBitsCloud
  .withUser('83hs026fbn2pqw=27qbs91571k')
  .withDevice('71d1hoa610')
  .settings({ input_interval_ms: 50 })
  // ...

Currently path-params are not customizable so we're stuck with device_id e.g.

output({device_id: 'foo', percent: 50})

We could use deviceId but wow that would suck. We could use id or device.

I solved this type of problem before forsubscriber_id and publisher_id by using subscriber and publisher. Similarly I think I prefer device here:

output({device: 'foo', percent: 50})

If we had snake_case support in the community I wouldn't think twice about renaming these keys.