v4 api client review

[Haroenv]

some breaking changes that need to happen

• multipleQueries
  • add strategy
• browseAll -> browse with async iterator
• browseAll method gone
• browseFrom({ ?query, ...browseParams, ?cursor})
• be careful about requesterOptions
• make requestOptions simpler
  • if known: header
  • if not known: query param
  • accept both longhand and shorthand: algoliaAgent, x-algolia-agent
• listIndexes keep page or remove it?
• addApiKey -> acl, not acls
• remove api key methods on index
• partialUpdateObject (createIfNotExists=true)
• test if getLogs works correctly

[vvo]

browseFrom({ ?query, ...browseParams, ?cursor})

browseFrom({searchParameters}, {cursor}) seems more inline with what we would have in V4

[vvo]

accept both longhand and shorthand: algoliaAgent, x-algolia-agent

What is the reasoning behind that? Everytime you have two ways to do one thing we take the risk of confusing people that would ask "In which situations I would do X with Y and not Z?"

If we want to pass raw headers, it should be headers: {} and not rely on a regex like [a-z]-[a-z]..

[Haroenv]

I agree, but @maxiloc told me requestOptions were implemented like that in other languages. cc @julienbourdeau

[maxiloc]

The request options must support both headers and URL parameters (at least). However, for optimal DX, the customer should not care whether an option translates into a header or a URL parameter. That should be the API client’s job to decide what goes where. Some clients (typically the JS client) may actually decide adaptively based on the context (browser vs server-side), the value’s size, etc.

From the spec of requestOptions

[vvo]

Yes I agree with that (and advocated for it) but what's the purpose of supporting the two forms if we do the automatic translation to headers or url parameters.

accept both longhand and shorthand: algoliaAgent, x-algolia-agent

[Haroenv]

all right, then it should be clear that we only support shorthands

[julienbourdeau]

Personaly, I don't really like the shorthands. I'm not sure agoliaAgent instead of X-ALGOLIA-AGENT makes it simpler.

[vvo]

We should all sync on this subject before taking a decision. Indeed it's tricky

[nunomaduro]

This v4.0 is in progress, and we took into consideration all those points.