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

RachelElysia commented 3 months ago

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

Step 1
Step 2
Step 3

Testing notes

Confirmation

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

noahtalerman commented 3 months ago

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 commented 3 months ago

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

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 commented 2 months ago

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

noahtalerman commented 2 months ago

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

Removing ~feature-fest and ~engineering-initiated

FYI @lukeheath and @RachelElysia

lukeheath commented 2 months ago

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

noahtalerman commented 1 month ago

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.

fleetdm / fleet