docs(appium): add an example for getSessions endpoint and add Deprecated for endpoionts which have no vendor key in the path and not in w3c spec

[KazuCocoa]

Proposed changes

https://github.com/appium/appium-inspector/pull/1369/files#r1510701460

It looks like we should put an example of the response of /sessions since it is not in W3C webdriver spec. This example would help.

e.g. https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessions

Types of changes

What types of changes does your code introduce to Appium?
Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update (if none of the other choices apply)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• I have read the CONTRIBUTING doc
• I have signed the CLA
• Lint and unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works
• I have added the necessary documentation (if appropriate)
• Any dependent changes have been merged and published in downstream modules

Further comments

If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...

[mykola-mokhnach]

we should mark this endpoint as deprecated and not recommended for use, same as getSession one as they are not part of the W3C spec.

[KazuCocoa]

makes sense. I have added a few deprecated marks by following this file's others.

[eglitise]

Are there any replacements for those deprecated endpoints? They might be used in the Inspector.

[KazuCocoa]

No for now I believe.
I think the inspector can be just "attach to a session" and users should give explicit session id. Current attach to an existing session does not let a user set an arbitrary session id by themselves, but it can have such setting an arbitrary session id to "attach to" the session.

[eglitise]

That would be a lot more inconvenient than the current process of automatic session discovery. Maybe this information can be added in the /status endpoint response, similarly to Selenium Grid? And for GET session/:sessionId, maybe something like GET /session/:sessionId/appium/info?
Can't comment on getLog and getLogTypes, but those could also just be moved to the corresponding /session/:sessionId/appium/... endpoint.

[KazuCocoa]

Then, we might need to add mobile: getSessions as current base method to define additional commands not in w3c webdriver spec.

/status should be ready and message https://www.w3.org/TR/webdriver2/#status , so not for this usage.

[KazuCocoa]

ah, or maybe we could define the /sessions endpoint in a new plugin? but not in the base driver?

[eglitise]

mobile: getSessions sort of implies it isn't compatible with other Appium-supported platforms like Mac. And while having this in a separate plugin is feasible, from a user perspective it would feel quite arbitrary to separate this.

I think /status could still work here because while it has to include ready and message, it "may additionally include arbitrary meta information that is specific to the implementation". Selenium Grid also seems to do this, though I'm not sure if its /status endpoint is W3C-compliant.

[KazuCocoa]

then it looks like a new plugin for it would be nice. I don't know that response format by the grid, so we may need to check the response format first.
e.g. selenium-grid-status plugin for the new /status format like the grid usage (need to check the format), sessions-plugin to keep /sessions

[KazuCocoa]

#19856 for the plugin

[eglitise]

At this point I would prefer if the deprecation labels were moved to a separate PR and merged after #19856/#19857/#19858

For the label format in MkDocs, it would also be better to use something like

!!! warning "Deprecated"

    Please use the `<endpoint>` endpoint instead

XCUITest driver docs already use this format.

[KazuCocoa]

Sure, then this pr can drop deprecated marks from sessions and session/<session_id>. These should be ok, and will create another Pr to modify the format with existing ones as well. -> #19859

Btw, other Appium clients will drop/dropped these endpoint call (since dependent selenium already dropped them) so maybe the appium-inspector usage is the main discussion focus right now.