API documentation regarding filter creation is unclear

[bocops]

Create a filter states that an integer value for expires_in should be given, and that this value will be interpreted as "How many seconds from now should the filter expire?". Documentation neither states that this value is optional, nor that some specific value (I assume "0") will be interpreted as a request for a filter that does not expire.

Non-expiring filters do exist, the Filter entity has an expires_at String value that is "null if the filter does not expire".

Please add documentation detailing how to create a non-expiring filter.

[trwnh]

anything not marked "required" is optional

i suppose default values could be called out, though?

[bocops]

anything not marked "required" is optional

Makes sense given the "REQUIRED" tag on some values. I was probably confused switching between methods and entities while implementing some of it, because the latter explicitly marks some of its values as "OPTIONAL". I couldn't find this spelled out on either Getting started with the API and Guidelines and best practices, so unless I've searched in the wrong locations, I'd suggest making this explicit at least once, somewhere.

i suppose default values could be called out, though?

Definitely. I'm working on a Kotlin/Java Mastodon library, and trying to find all the implicit default values in the server code is quite hard at times.

[trwnh]

the following callouts are used throughout the api docs:

methods

• "required" = if you don't provide this for a method, the method call will fail

entities

• "optional" = the entity attr may not be present
• "nullable" = the entity attr may be present as an explicit null value

---

i can probably add this clarification to the pages you mentioned above, yeah. maybe even an explainer on hover?

[bocops]

That would be nice, especially the idea of an onHover tooltip sounds great!

[andypiper]

@trwnh I'm going through to label API-related docs issues; I'm very happy if you want to pick this up ahead of me, however - you have much more familiarity with the docs and API at this time 👍🏻

[nikclayton]

Because I've just bumped in to this the explainer in https://github.com/mastodon/documentation/issues/1216#issuecomment-1546937310 isn't relevant for this issue (mostly because the data is FormUrlEncoded, not JSON encoded).

For completeness:

If you set expires_in to 0 it's treated as "expires immediately" (which makes sense, it expires 0 seconds from now).

If you set expires_in to the literal string null it's treated as 0 (not sure if that's deliberate intention, or the result of error handling on the backend).

To get a filter that does not expire the expires_in value must be the empty string (not a quoted empty string, which would be expires_in=%22%22, but just expires_in=).

Treating this as a nullable int is problematic in some libraries. Retrofit, at least, will not send nulls as values in FormUrlEncoded requests, they have to explicitly sent as empty strings.

Ideally, a v3 of the filters API would fix this by, amongst other things, ditching the form encoding and using JSON like the rest of the API. To quote from https://url.spec.whatwg.org/#application/x-www-form-urlencoded:

The application/x-www-form-urlencoded format is in many ways an aberrant monstrosity, the result of many years of implementation accidents and compromises leading to a set of requirements necessary for interoperability, but in no way representing good design practices. In particular, readers are cautioned to pay close attention to the twisted details involving repeated (and in some cases nested) conversions between character encodings and byte sequences. Unfortunately the format is in widespread use due to the prevalence of HTML forms. [HTML]