Document how to set fields in `PATCH /config` endpoint to empty

[RachelElysia]

Goal

User story
As a Fleet contributor or Fleet API user looking at the PATCH /config endpoint in REST API docs,
I want to know how to set specific fields to empty (ex. null, 0, omit)
so that I know how to use the PATCH /config endpoint.

Context

• Requestor(s): @RachelElysia
• Product designer: @rachaelshaw

Changes

Product

• [ ] UI changes: TODO
• [ ] CLI usage changes: TODO
• [ ] REST API changes: TODO
• [ ] Permissions changes: TODO
• [ ] Outdated documentation changes: TODO
• [ ] Changes to paid features or tiers: TODO

Engineering

• [ ] Database schema migrations: TODO
• [ ] Load testing: TODO

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Requires load testing: TODO
• Risk level: Low / High TODO
• Risk description: TODO

Manual testing steps

1. Step 1
2. Step 2
3. Step 3

Testing notes

Confirmation

1. [ ] Engineer (@____): Added comment to user story confirming successful completion of QA.
2. [ ] QA (@____): Added comment to user story confirming successful completion of QA.

[noahtalerman]

Thanks for tracking this @RachelElysia!

Users should know what fields can be undefined, or defined as null and why.

If I'm understanding correctly, the problem is that it's not clear what the best practice is for defining empty values for options in the PATCH /config endpoint.

As an API user, when should I set an option to null v. empty string v. undefined?

Rachel, which options could use this best practice?

Maybe we solve this w/ updates to the PATCH /config docs.

FYI @rachaelshaw

[noahtalerman]

Hey @RachelElysia, because we pulled this story into the current design sprint, I updated the issue description to user story format.

I moved your original issue description here for safekeeping:

Problem

• The frontend should work seamlessly with the API.
• Users should know what fields can be undefined, or defined as null and why.
• Users should know how to properly patch to /config

Potential solutions

1. Address FE painpoints and determine if they are painpoints only in our frontend code, or if they are also found as painpoints in our API and documentation of our API.

• Which values can be undefined? Which values can be set to null? Which values can be set to 0? Which values will be undefined or null instead of an empty string?

[rachaelshaw]

@RachelElysia this didn't make it through the current design sprint, bringing back to Feature Fest

[noahtalerman]

I think this story meets the definition of an engineering initiated story.

Removing ~feature-fest and ~engineering-initiated

FYI @lukeheath and @RachelElysia

[lukeheath]

@RachelElysia Thanks for filing this! I'm prioritizing for estimation.

[noahtalerman]

Chatting w/ @ddribeiro: Dale was building an iOS app on top of the Fleet API and not knowing which fields return null, 0, empty string was tough.

Getting this wrong would crash the app in some instances.

Probably a separate story but just leaving this here.

[noahtalerman]

Nice! Thanks @RachelElysia

[fleet-release]

Fields in patch cleared, Fleet's guide offers insight, Users steer with light.