Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

apiGeneral: calls: clarify internal IDs #1961

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions shared/apiGeneral/calls.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ curl -X GET "{{ $links.apiBase }}/v5/device(<ID>)" \
-H "Authorization: Bearer <AUTH_TOKEN>"
```

## 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
Expand All @@ -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
Expand Down