Make some API parameters optional and blank=all

You have two viable UX patterns here:

---

## 1) **Make every parameter required**

Pros:

* **Uniformity**: every request looks the same, no “magic defaults.”
* **Schema validation**: OpenAPI can enforce that every field is present.

Cons:

* **Verbosity**: clients always need to send `…&dimensions[segment][level1]=all` even when they want the default.
* **Discoverability**: people might forget which “all” keyword to use.

---

## 2) **Treat some parameters as optional with defaults**

For example, you could:

* In your OpenAPI schema mark `dimensions.segment.level1` as **not** required.
* In your handler, if `segFilter` is missing or `undefined`, you internally treat it exactly like `"all"`.

Pros:

* **Concise requests**: `?period[…]&dimensions[geography]…` automatically gives you all segments, no extra query param needed.
* **Cleaner for simple uses**: users who only care about geography or time don’t need to think about segments.

Cons:

* **Implicit behavior**: clients need to know that “omitting” means “all.”
* **Validation nuance**: your JSON schema has to allow the property to be absent.

---

### My recommendation

1. **Make “segment” optional** in `parameters.yaml` (remove it from `required:`).

2. In your code, do something like:

```js
const segFilter = dimensions.segment?.level1 ?? 'all';
```

so missing or null becomes `'all'`.

3. **Document** in your parameter description that if `segment` is omitted, the API returns “all segments.”

That gives you the best DX: concise calls for the 90% case, and still full power when you need to drill down.