From ca2a387aab0bf2bfdaeecdb711c6d43f4b0b7319 Mon Sep 17 00:00:00 2001 From: Joseph Kogut Date: Fri, 2 Jul 2021 16:45:20 +0000 Subject: [PATCH] apiGeneral: calls: clarify internal IDs Also add a header above the section detailing usage of internal IDs for permalinking. Change-type: patch Signed-off-by: Joseph Kogut --- shared/apiGeneral/calls.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/shared/apiGeneral/calls.md b/shared/apiGeneral/calls.md index b1392363bc..abe003259e 100644 --- a/shared/apiGeneral/calls.md +++ b/shared/apiGeneral/calls.md @@ -46,6 +46,8 @@ curl -X GET "{{ $links.apiBase }}/v5/device()" \ -H "Authorization: Bearer " ``` +## Resource IDs + Many times, however, you won't know the internal ID used by the API, and you'll want to use some other piece of information to find the appropriate resource. In these cases, you can use the `$filter` method to select resources based on any field. For example, if you are looking for a specific device, it's more likely that you'll have the device UUID than the device ID: ```shell @@ -57,6 +59,10 @@ curl -X GET \ Notice the construction here: `$filter=` is used to define the field, and then the value is specified after the `eq` keyword. This is the most straightforward example—there are many other ways to build filters, which you can find in the OData documentation. +The resource returned from this call contains the internal ID you can use to make subsequent calls, under the "id" key. + +`{"d":[{"id":1234567, ...` + A final tip for constructing API calls: for some of the fields in the API response, a link to another resource is provided rather than the complete information about that resource. For example, if you make a call requesting information about a specific device, the `belongs_to__application` field will return a link to an application, but not all the information about that application. To get all the fields for the application resource, you can use the `$expand` method: ```shell