API 2.3 Release

feature-requeststatus-completed

The Stack Exchange API uses snake_case for all fields so far. However, the new collective-report type has three fields in PascalCase: ActivityReportDimensions, HealthReportDimensions, UsersReportDimensions. IMHO it's not too late to change those names to conform to the unwritten rules; consistency is everything. You certainly don't want to let your API look like PHP ...

status-completed

The 2.3 version of the API introduced the ability to suggest an edit (older versions did support editing, but only if you have edit privileges). Does that still work? It is not mentioned in the change log. The mobile apps used related fields (can_edit, can_suggest_edit) on the post object to determine what kind of edit action was necessary, what about those?

This comment mentions tag preferences. I've never used that API but it's something to consider as well.

Finally, you might want to write an answer to my question on Stack Apps: Please "release" and/or document API version 2.3

bug status-completed

On the top of the documentation page it says Stack Exchange API v2.2 and in the first paragraph

This is the documentation for the v2.2 Stack Exchange API

I think you want it to say 2.3 there.

Under the the heading articles it says:

Add/Edit/Delete Only available for Business Teams via the Teams API.

That doesn't seem to be true. Works (kind of) for me on Stack Overflow.

bugstatus-completed

The documentation page for the collective type contains a link to the collective-external-link type, which 404s.

bugstatus-completed

The /articles endpoint returns a link that isn't correct. For example this one. It points to:

https://stackoverflow.com/articles/68104924/listen-for-authentication-state-in-android

while the actual acticle link is:

https://stackoverflow.com/collectives/google-cloud/articles/68104924/listen-for-authentication-state-in-android

bug spellingstatus-completed

There appears to be a spelling mistake (one of many) on the Usage by collective page:

I think you want that to say "identified". "An question" should be "A question".

In order to implement retracting flags, I investigated a bit as to what's required in order to do so. In the process, I encountered several issues:

1. It's impossible to know if an "in need of moderator intervention" (i.e. custom) flag has been raised and it's impossible to retract such custom flags.

Even while a custom flag is raised, the provided flag option is always is_retraction: false and does not contain a has_flagged property.

Given that a user can re-raise custom mod flags multiple times, the has_flagged property is probably better used to effectively mean "there is a custom flag currently active", or, effectively, "can_not_raise_new_flag_right_now".

2. It is impossible to tell which flag is currently active

Once a user has raised a flag, the responses for each of types they have raised, regardless of if the flag has been retracted or handled, always have has_flagged: true, is_retraction: true, and an option_id. Once the flag has been retracted or handled, there should be some indication that it's no longer possible to retract. Probably the best thing would be to just not have is_retraction: true and no option_id.

In other words, what's received from the API is identical in the following states:

1. Can retract: flag currently raised and active (not yet handled)
2. Can't retract: flag previously raised, but not active (already handled), or flag previously raised, but not active (user has retracted)

Without being able to differentiate between these, to retract a flag, one has to walk through trying to retract every possible entry. This could include 30+ options (if close-votes/flags are changed to work for retracting). That is, potentially, a substantial number of requests in order to retract a single flag. Ideally, if the user can't retract or raise a flag, then there should not be either an is_retraction: true or an option_id property.

NOTE: Custom moderator flags can be raised again, even if previously handled or retracted. So, it should not be assumed that just because a user has already retracted they can't re-raise a flag. That they can't re-raise a flag is the case for other types of flags, but not, at least, close-flags which can age away and be re-raised. I'm not sure if other aged-away flags can be re-raised.

3. If a spam or R/A flag has been raised, then both flag types show has_flagged: true and is_retraction: true, but only one works to retract.

You can't raise or retract the one of these flag types which the user hasn't already raised. The one which hasn't been raised should either have a new property like can_flag: false, just not be returned as an option, or be returned with no has_flagged, no is_retraction, and no option_id (i.e. indicate that the user hasn't actually raised it, but that they can't raise or retract it).

NOTE: Don't make the assumption that users can never raise both a spam and R/A flag, because moderators can do that, just not at the same time (and it's a useful capability in some cases).

4. Can't retract close-votes or close-flags (also reported by Xnero here)

• When a close-vote or close-flag is raised, the top level options for closing indicate is_retraction: true, but don't contain an option_id. None of the sub_options have is_retraction: true, but each contains an option_id, which doesn't work for retracting.
• Once a close-flag or close-vote is raised, /questions/{id}/close/options returns no data.
• There should be a single option_id which is for retracting the close-flag/vote. It's detrimental to have to select whichever of the sub_options was selected by the user when raising the flag in order to retract it (i.e. you should be able to retract by using an option_id provided on the top level of the flag options description list).
• Currently, when a close-vote/flag is active, /questions/{id}/flags/options returns >25 separate option_id values which ostensibly permit raising an additional close-vote/flag (but don't work to do anything other than get an error).

There should only ever be a single flag option with is_retraction: true and an option_id returned by the API.

If a flag is currently raised and there's only one option_id which will actually function to retract the currently raised flag, then there should be only a single flag option Object returned which has both is_retraction: true and an option_id. If there are options provided where both of those are present, but which won't actually work, then the API is returning data that's really invalid. In fact, the API should only ever be returning option_id values which the user could actually use, so under the conditions of having a currently active flag, and assuming we can't raise more than one flag at a time, then there should be only a single option_id provided in the entire data returned by the API, as there's only one such option_id that is actually valid at the time the request is made of the API to provide the current valid flagging options for the user.

feature-request retracted-flags

Please don't make flag retraction use the exact same query as casting flags

Currently, if someone uses a query to cast a flag, /flags/add, and the same user has already cast the exact same type of flag, it will cause the flag to be retracted. As per this staff post, this behavior is intentional for this new version of the API.

However, this behavior isn't ideal. For starters, it's not semantically correct to remove a flag on receiving a command to cast a flag. It can result in problems where if someone submits the same query twice, either by accident or in order to ensure that their first attempt went through if they're not sure of that, the flag will be unexpectedly removed. Second, it makes current API 2.2 scripts much more difficult to port to the new API, especially scripts that depend on errors being received upon trying to recast an already-cast flag. Those scripts will have to use more API quota for this purpose, as they'll have to make a second call to ascertain if a flag was already cast.

Can this design feature please be removed (i.e. reverted to how it used to work in 2.2, with errors being returned instead of flags being retracted), and it replaced with another, explicit way to retract flags, such as a query parameter ?is_retraction=1 or a separate endpoint such as /flags/retract?

bugretracted-flags

Recommended closure flags cannot be retracted

If a question is flagged as any "needs improvement" option or as a "duplicate", is_retraction is set to true for both "a duplicate" and "needs improvement" but no option_id is provided for either option making it impossible to retract the flag from the API.

Expected API output for any other type of flag:

Output for any "needs improvement" or "duplicate option" (notice the absence of option_id):