-
-
Notifications
You must be signed in to change notification settings - Fork 973
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API documentation regarding filter creation is unclear #1216
Comments
anything not marked "required" is optional i suppose default values could be called out, though? |
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.
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. |
the following callouts are used throughout the api docs: methods
entities
i can probably add this clarification to the pages you mentioned above, yeah. maybe even an explainer on hover? |
That would be nice, especially the idea of an onHover tooltip sounds great! |
@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 👍🏻 |
Because I've just bumped in to this the explainer in #1216 (comment) isn't relevant for this issue (mostly because the data is FormUrlEncoded, not JSON encoded). For completeness: If you set If you set To get a filter that does not expire the 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:
|
Mastodon API uses an "empty" `expires_in` value for a filter to mean "Does not expire" (i.e., indefinite). This was modelled as a null. Which doesn't work, because Retrofit does not send name/value pairs in encoded forms if the value is null. Fix this by making the API type a `String?`, and explicitly using the empty string when indefinite expiry is used. This has to be converted back to an Int? in a few places. See mastodon/documentation#1216 (comment)
Mastodon API uses an "empty" `expires_in` value for a filter to mean "Does not expire" (i.e., indefinite). This was modelled as a null. Which doesn't work, because Retrofit does not send name/value pairs in encoded forms if the value is null. Fix this by making the API type a `String?`, and explicitly using the empty string when indefinite expiry is used. This has to be converted back to an Int? in a few places. See mastodon/documentation#1216 (comment)
Mastodon API uses an "empty" `expires_in` value for a filter to mean "Does not expire" (i.e., indefinite). This was modelled as a null. Which doesn't work, because Retrofit does not send name/value pairs in encoded forms if the value is null. Fix this by making the API type a `String?`, and explicitly using the empty string when indefinite expiry is used. This has to be converted back to an Int? in a few places. See mastodon/documentation#1216 (comment)
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.
The text was updated successfully, but these errors were encountered: