More clarification. Replace inline hyperlinks with reference style.

doc/api/README.md

@@ -220,7 +220,7 @@ Impersonation tokens are used exactly like regular personal access tokens, and c
 ### Sudo
 
 NOTE: **Note:**
-Needs admin permissions.
+Only available to [administrators][permissions].
 
 All API requests support performing an API call as if you were another user,
 provided you are authenticated as an administrator with an OAuth or Personal Access Token that has the `sudo` scope.
@@ -446,7 +446,7 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \
 
 ## `id` vs `iid`
 
- Some resources have two similarly-named fields. For example, [issues](issues.md), [merge requests](merge_requests.md), and [project milestones](milestones.md). The fields are:
+ Some resources have two similarly-named fields. For example, [issues], [merge requests], and [project milestones]. The fields are:
 
 - `id`: ID that is unique across all projects.
 - `iid`: additional, internal ID that is unique in the scope of a single project.
@@ -454,7 +454,7 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \
 NOTE: **Note:**
 The `iid` is displayed in the web UI.
 
-If a resource has the `iid` field, it is often used instead of `id` to fetch the resource.
+If a resource has the `iid` field and the `id` field, the `iid` field is usually used instead of `id` to fetch the resource.
 
 For example, suppose a project with `id: 42` has an issue with `id: 46` and `iid: 5`. In this case:
 
@@ -462,7 +462,7 @@ For example, suppose a project with `id: 42` has an issue with `id: 46` and `iid
 - An invalid API call to retrieve the issue is `GET /projects/42/issues/46`.
 
 NOTE: **Note:**
-Not all resources with the `iid` field are fetched by `iid`.
+Not all resources with the `iid` field are fetched by `iid`. For guidance on which field to use, see the documentation for the specific resource.
 
 ## Data validation and error reporting
 
@@ -562,3 +562,7 @@ programming languages. Visit the [GitLab website] for a complete list.
 [ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
 [ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099
 [pat]: ../user/profile/personal_access_tokens.md
+[issues]: issues.md
+[merge requests]: merge_requests.md
+[project milestones]: milestones.md
+[permissions]: ../user/permissions.md