Reset Stop-Words and Synonyms Settings With A Null Value

[gmourier]

Summary

All Sub Settings POST endpoint accepts a null value in the http request body to reset the engine configuration to the default values. This is not the case for Stop-words and Synonyms settings endpoints.

Motivation

This specification is written to make the above mentioned routes consistent with the others.

[ManyTheFish]

I don't like the idea, I don't think that null is considered equivalent to [] in everybody's mind. It could be interpreted as the absence of the field.

I would prefer that the user explicitly set the field to [] if he wants to reset it.

[curquiza]

The other settings (for example seachableAttributes and displayedAttribtutes) already accept null as value to reset the settings, so to fill the settings to [].
Even if this possibility is not documented, we know it is already used by some users: we saw it in the integration issues we had. So for me, this spec is a good idea:

• the users that don't have the habit to use null are still not impacted and the feature is still not documented.
• the users who used null to reset can now do it consistently for synonyms and stop-words.
• put [] is still available to reset the settings, and the DELETE routes as well.

[gmourier]

Sorry @ManyTheFish, I forgot to answer you I got caught elsewhere. Your proposal goes in the direction of an API that can be fully documented. Personally, I'm not a fan of having a hidden workaround that is not documented. The API format specification will solve this kind of case. However, it is important to keep in mind that sometimes we have to make deviations to keep a good DX.

@curquiza, it's true for the 0.21 release, we cut in the fat to advance towards the release. However, your answer makes me wonder about two questions that we can deal with in future releases.

1. Integrations could accept a null value in the parameters of the update sub-setting method and transform it into [] or {} or even call the DELETE method in this case. So the update method will be a facade in this particular case.
2. If I understand correctly people don't call the reset methods from integrations? So do we need to keep these? Analytics on the feature level will tell us that to make a decision about that.

[curquiza]

1. If this feature is a problem from your POV, moving it to the SDKs is just move the "problem" into 8 different repos (so duplicate the code) instead of one. Even in the SDKs, it will not be documented to avoid making the README and the docs heavier. So, from my POV, either we keep it everywhere, or not.
2. The majority call the reset method. But some of them use the update method as well. That's why I thought it's a nice feature to have for people noticing it because it's intuitive for them, without disturbing people that classically use the reset route. So it is really worthy to remove this feature? But if you would rather remove this possibility, I'm following 🙂

However I would add I've never seen someone reporting they have been confused about accepting the null value at the moment. So re-doing all this settings behavior instead of just making it consistent might be a lot of work in the transplant size for nothing (again, regarding the absence of current complaint).

[gmourier]

Agreed on the fact that the first proposal will shift the effort to the X integration libs. Probably not a good idea, as you pointed out this is something that is important to keep in mind. I don't really see a problem with having this null value in the POST even though it's something that seems unusual and might surprise some developers as well. As I said earlier, making some deviations to keep a good DX is sometimes necessary.

We need factual stats on the use of these routes to talk about this again. The fact is that we have two routes that accomplish the same thing. Is this a problem at the moment? You tell me no from the user feedback you get! The advantage is that we will have a consistent behavior on the whole scope of the sub-settings routes with this specification.

It's not an immediate priority anyway if we have no complaint about it and no quantitative statistics. Let's move forward on this specification as such 😉

[curquiza]

Even if your decision is made, I want to share this smart way of usage 😊 It might be intersting.
Some users (sorry I cannot find where their feedback was, since it was several months ago) use the null value when calling the general update route (POST /indexes/:uid/settings ) in order to update and reset setting at the same time!

Example:
Calling POST /indexes/:uid/settings with

{
    "searchableAttributes": null,
    "displayedAttributes": [
        "title"
    ]
}

will reset the searchable attributes and will update the displayed attributes at the same HTTP call.

If we remove the possibility to use the null value to reset, it will remove this possibility.

[ManyTheFish]

Even if your decision is made, I want to share this smart way of usage 😊 It might be intersting.
Some users (sorry I cannot find where their feedback was, since it was several months ago) use the null value when calling the general update route (POST /indexes/:uid/settings ) in order to update and reset setting at the same time!

Example:
Calling POST /indexes/:uid/settings with

{
    "searchableAttributes": null,
    "displayedAttributes": [
        "title"
    ]
}

will reset the searchable attributes and will update the displayed attributes at the same HTTP call.

If we remove the possibility to use the null value to reset, it will remove this possibility.

What about:

Calling POST /indexes/:uid/settings with

{
    "searchableAttributes": [],
    "displayedAttributes": [
        "title"
    ]
}

This would be similar to your example.

[curquiza]

Calling POST /indexes/:uid/settings with

{
    "searchableAttributes": [],
    "displayedAttributes": [
        "title"
    ]
}

This would be similar to your example.

From my POV, this means "I don't want any searchable attributes, and only title as displayed attributes". It's not a reset.

[ManyTheFish]

My bad @curquiza, I miss understood the meaning of reset. 😅
You're right.