search

TheThingsIndustries / lorawan-stack-docs

Documentation for The Things Stack
Apache License 2.0
32 stars 65 forks source link

Improve the API fields data type information in the API documentation #1101

Open ymgupta opened 1 year ago

ymgupta commented 1 year ago

Summary

The Things Stack users are often confused with API field data types i.e., in the documentation API field type type: bytes does not imply base64. Also, the type of API field interpreted should depends on the actual message. For example, the frm_payload of the ApplicationDownlink is read as a base64 type, whereas the dev_eui field of the EndDeviceIdentifiers is read as hex.

Why do we need this ?

To help users in distinguishing between different data types of API fields.

What is already there? What do you see now?

https://www.thethingsindustries.com/docs/reference/api/

What is missing? What do you want to see?

API fields with more details on the data types/examples. @adriansmares , could you please add your insights here?

How do you propose to document this?

...

Can you do this yourself and submit a Pull Request?

No, @nejraselimovic

adriansmares commented 1 year ago

We need to update our tooling in order to deal with this inconsistency. I will pick this up.

KrishnaIyer commented 1 year ago

@adriansmares: It would be great if you could find some time to pick this up this month.

KrishnaIyer commented 10 months ago

I'll pick this up as part of the API documentation item that I'm working on.

nejraselimovic commented 7 months ago

hey @KrishnaIyer was this covered in https://github.com/TheThingsIndustries/lorawan-stack-docs/pull/1230?

KrishnaIyer commented 7 months ago

I think this requires a few small updates to the generated docs. I'll pick this up later this month.