API design: which value should return an API method?

Option 1

Pros:

• easy to use
• destructuring assignment for the win

Cons:

• Quite a significant breaking change (but is not that hard to migrate)
• Forces the use of HTTP names (less future proof)

client.search({ params }, (err, result) => {
  console.log(result)
  // {
  //   body: Object,
  //   headers: Object,
  //   warnings: Array,
  //   statusCode: Number
  // }
})

Option 2

Pros:

• no breaking change
• future proof

Cons:

• higher cognitive overhead

const { kMeta } = require('@elastic/elasticsearch') // kMeta is a Symbol and you must import it from the client
client.search({ params }, (err, body) => {
  console.log(body) // elasticsearch response
  console.log(body[kMeta])
  // {
  //   headers: Object,
  //   warnings: Array,
  //   statusCode: Number
  // }
})

Option 3

(note the asHttpResponse parameter, the default is false) Pros:

• no breaking change

Cons:

• change the returned value based on a parameter can cause unexpected side effects
• typescript will complain
• not future proof, if in the future we will add a new transport method we will need to add another parameter to expose its metadata

client.search({ params, asHttpResponse: false }, (err, body) => {
  console.log(body) // elasticsearch response
})

client.search({ params, asHttpResponse: true }, (err, result) => {
  console.log(result)
  // {
  //   body: Object,
  //   headers: Object,
  //   warnings: Array,
  //   statusCode: Number
  // }
})

Option 4

Pros:

• no breaking change
• the symbol is hidden, so less cognitive overhead than option 2
• future proof

Cons:

• higher cognitive overhead

const { getMeta } = require('@elastic/elasticsearch') // getMeta is a function that reads the kMeta symbol inside the body
client.search({ params }, (err, body) => {
  console.log(body) // elasticsearch response
  console.log(getMeta(body))
  // {
  //   headers: Object,
  //   warnings: Array,
  //   statusCode: Number
  // }
})

---

If you want you can “vote” in this way:

• 👍 for option 1
• 😄 for option 2
• 🎉 for option 3
• ❤️ for option 4

[epixa]

The benefit of option 1 is that it is a pattern for http clients that is widespread throughout all languages I’ve worked with. Headers and responses codes are a first-class feature of the elasticsearch api (and a critical part of REST im general), so building a client that treats them as second class things is a strange choice to me.

I disagree about the easy of use comment because it’s less consistent with every http client I’m familiar with, which makes it harder for me to use. That’s purely annecdotal though, so take it with a grain of salt.

If not option 1, then option 4 is the only other option I like.

[stale[bot]]

We understand that this might be important for you, but this issue has been automatically marked as stale because it has not had recent activity either from our end or yours. It will be closed if no further activity occurs, please write a comment if you would like to keep this going.

Note: in the past months we have built a new client, that has just landed in master. If you want to open an issue or a pr for the legacy client, you should do that in https://github.com/elastic/elasticsearch-js-legacy