tailscale / tailscale/tailscale
Misleading API Documentation Regarding Tailnet and Orgname Usage
- Dominant language
- Go
- Stars
- 36.5k
- Forks
- 3.2k
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 132
Description
### What is the issue?
While using the Tailscale API, I encountered inconsistencies with how the terms "tailnet" and "orgname" are defined and applied. This has led to significant confusion and errors during implementation.
According to the current API documentation, one should use the "tailnet" identifier when making a call. For example, it suggests using the endpoint `GET /api/v2/tailnet/{tailnet}/acl`.
However, when implementing this as suggested, I consistently encountered errors. Through my troubleshooting process, I discovered that instead of using the "tailnet" as per the API documentation, it is the "orgname" that should be used in its place for the API call to work effectively. Consequently, the correct API call seems to be `GET /api/v2/tailnet/{orgname}/acl`.
In the Tailscale UI, the "tailnet" and "orgname" appear in different places and they are not the same. The "tailnet" is found within the settings and is presented as a URL, whereas the "orgname" is located at the top left corner of the UI and it's not the same as the "tailnet".
I believe this discrepancy in the documentation may pose challenges for users attempting to use the API effectively. It would be beneficial to clarify this in the API documentation to ensure accurate implementation in the future.
### Steps to reproduce
Follow the current documentation.
### Are there any recent changes that introduced the issue?
Not that I'm aware of.
### OS
Linux, macOS, Windows
### OS version
Latest
### Tailscale version
Latest
### Other software
N/A
### Bug report
_No response_
Contributor guide
Research direction
Start by locating the API documentation for GET /api/v2/tailnet/{tailnet}/acl and review how “tailnet” and “orgname” are defined. Clarify which identifier the endpoint expects, update the example and terminology, and verify that the documented call matches the reported behavior.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100