apiGeneral: calls: clarify internal IDs

[jakogut]

Also add a header above the section detailing usage of internal IDs for
permalinking.

Signed-off-by: Joseph Kogut joseph@balena.io

A user of the API encountered some confusion over usage of internal IDs. Searching yielded the linked issue already describing the problem, and the need to clarify usage of internal IDs. Reading through the docs yielded a page that mostly already clarifies this, but it's part of a larger page on constructing API calls, and can't be linked to on the section for finding and using resource IDs.

Add an H2 header to enable linking, and add a sentence explaining which field for a returned resource is the internal ID.

Related-to: #1881

[vipulgupta2048]

Thanks for taking this up @jakogut Maybe an example would help?

I had it in mind where we can show the output of the /v6/device resource, and specifically pointing out the find DEVICE_ID value. Then, mentioning similar instructions for APPLICATION_ID as well. This clearly defined example would help folks out on support.

[jakogut]

we can show the output of the /v6/device resource, and specifically pointing out the find DEVICE_ID value

@vipulgupta2048 This is added starting at line 62. I truncated the output, as the serialized object is quite lengthy, but I could change this to the complete output using select to only retrieve the ID field.

[jakogut]

@balena-ci rebase

[vipulgupta2048]

@jakogut I would say providing at least some more fields would be nicer

{
a : c,
id : {ldfndlf}
a1 : c,
a2 : c,
a3 : c,
a4 : c,
a5 : c,
...
}

If having a generalised query or process that would help folks in finding their ID's faster then I am all for it. Do put this under a small heading like h3 or h4 as appropriate. So support agents can use that when they are looking.