Improve description of field masks in API documentation

[benolayinka]

Summary

Closes https://github.com/TheThingsIndustries/lorawan-stack-support/issues/373
Closes https://github.com/TheThingsIndustries/lorawan-stack-support/issues/527

Screenshots

Changes

• Add missing messages and enums to API docs
• Properly describe field mask usage, add warnings
• Add that identifiers in body are not required if they are specified in url

Checklist

• Scope: The referenced issue is addressed, there are no unrelated changes.
• Run Locally: Verified that the docs build using make server, posted screenshots, verified external links. Test with HUGO_PARAMS_SEARCH_ENABLED=true if style changes will affect the search bar.
• New Features Marked: Documentation for new features is marked using the new-in-version shortcode, according to the guidelines in CONTRIBUTING.
• Style Guidelines: Documentation obeys style guidelines in CONTRIBUTING.
• Commits: Commit messages follow guidelines in CONTRIBUTING, there are no fixup commits left.

[htdvisser]

I'm afraid this "field mask only" label will make things even more confusing than they already are. As an example of this, your first screenshot shows the Applications message (for list responses) and indicates the applications field as needing to be in the field mask, which isn't the case.

Also, do we emphasize enough that empty fields (zero values) are omitted from the JSON, regardless of field mask? This is of course something we'd want to fix in a future version of The Things Stack but that's going to take some time.

[benolayinka]

I'm afraid this "field mask only" label will make things even more confusing than they already are. As an example of this, your first screenshot shows the Applications message (for list responses) and indicates the applications field as needing to be in the field mask, which isn't the case.

Can we somehow get a better list of which fields are field mask only, then? @johanstokking shared this but I don't understand how it's used https://github.com/TheThingsNetwork/lorawan-stack/blob/v3.14/pkg/ttnpb/field_mask_validation.go

[htdvisser]

Not really, because it also depends on the context.

• The ApplicationRegistry.Create RPC takes an Application in its request, but there is no field mask, it just looks at all fields.
• The ApplicationRegistry.Get and ApplicationRegistry.List RPCs take a request message with a field mask to indicate the fields to return.
• The ApplicationRegistry.Update takes both an Application and a field mask that indicates which fields to update.

---

I think the best way to document this, is to do it in the request messages, so in the GetApplicationRequest for example, we would document that the ids, created_at, updated_at fields are always selected. In entity messages (such as Application) we would then say that the fields that are returned/updated are selected in the request message.

[benolayinka]

Not really, because it also depends on the context.

• The ApplicationRegistry.Create RPC takes an Application in its request, but there is no field mask, it just looks at all fields.
• The ApplicationRegistry.Get and ApplicationRegistry.List RPCs take a request message with a field mask to indicate the fields to return.
• The ApplicationRegistry.Update takes both an Application and a field mask that indicates which fields to update.

I think the best way to document this, is to do it in the request messages, so in the GetApplicationRequest for example, we would document that the ids, created_at, updated_at fields are always selected. In entity messages (such as Application) we would then say that the fields that are returned/updated are selected in the request message.

Created a new issue for this -> #493

Will merge this as is, with improved description of how field masks work

[htdvisser]

These fields are always returned for messages that have them.
Only updated_at is automatically updated.

[htdvisser]

It depends on the request. Not all requests take field masks.

[benolayinka]

Updated, it looks like all requests which operate this way list a field_mask parameter, i.e https://www.thethingsindustries.com/docs/reference/api/application/#message:UpdateApplicationRequest or http://localhost:1313/reference/api/end_device/#message:GetEndDeviceRequest

[htdvisser]

I still think we can do better, but let's not block this any longer.

[nejraselimovic]

Suggested change

	{{< note >}} If you're having trouble with the HTTP API, you can always inspect requests in the Console using your browser's inspector. All of the data displayed in the Console is pulled using HTTP API requests, and this should give you some insight in to how they are formed.
	{{< note >}} If you are having trouble with the HTTP API, you can always inspect requests in the Console using your browser's inspector. All of the data displayed in the Console is pulled using HTTP API requests, and this should give you some insight in to how they are formed.