API Operation Update: GetDeviceDetails

[jshcodes]

API Operation Update: GetDeviceDetails

GetDeviceDetails is a commonly used API operation that is undergoing updates and introducing expanded functionality. On July 24th, 2023, the current API endpoint will be decommissioned. The replacement(s) for this operation are already in place. This post is intended to describe how FalconPy is handling these changes and to inform you of what changes may need to occur within your code and environment.

What's changing?

The API endpoint for the GetDeviceDetails operation is scheduled for deprecation. Code that makes a direct request to this endpoint (i.e., not leveraging an updated version of our SDKs) will in the future be unable to communicate with the endpoint and ultimately will fail. This operation has two replacements, both of which are available today for production use; PostDeviceDetailsV2 and GetDeviceDetailsV2.

Legacy endpoint details

Operation ID: GetDeviceDetails
Endpoint: /devices/entities/devices/v1 (GET)
Maximum IDs allowed: 500

New operation, added functionality

The new operation, PostDeviceDetailsV2, supports an ID maximum of 5,000. This is a ten-fold increase to the 500 currently supported in the legacy endpoint.

How is FalconPy addressing this change?

FalconPy will not be deprecating the GetDeviceDetails operation ID. Instead when this operation is called (regardless of method or if called from the Service or Uber Class) requests will be sent to the new PostDeviceDetailsV2 operation. Since this new operation is a POST and not a GET operation, the IDs submitted to the method are moved to the body payload for the developer automatically. This new redirection was implemented in v1.2.0 and is available now.

This means that code that leverages the GetDeviceDetails operation (either via the Service or Uber Classes) will not have to be updated, and will automatically start to benefit from the submitted ID maximum increase.

You must upgrade to version v1.2.0 or greater in order to benefit from this functionality.

GetDeviceDetailsV2

This operation leverages the same payload format as the previous GetDeviceDetails operation. Using the FalconPy SDK, you can access this operation with either the PEP-8 or Operation ID Syntax method (Service Class) or by operation ID (Uber Class).

Endpoint: /devices/entities/devices/v2 (GET)
Maximum IDs allowed: 100

Service Class usage

from falconpy import Hosts
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_device_details_v2(ids=id_list)
print(response)

PostDeviceDetailsV2 (now also GetDeviceDetails)

This operation leverages the same API endpoint as GetDeviceDetailsV2 but instead uses the POST HTTP method. FalconPy SDK users will not need to worry about this detail, as all of this is abstracted. You can access the functionality provided by this operation using either the GetDeviceDetails or the PostDeviceDetailsV2 methods.

Expected keywords for all methods discussed in this post are the same.

Endpoint: /devices/entities/devices/v2 (POST)
Maximum IDs allowed: 5000

Service Class usage

from falconpy import Hosts
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_device_details(ids=id_list)
print(response)

or

from falconpy import Hosts
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.post_device_details_v2(ids=id_list)
print(response)

Questions

Have a question about this change? Let us know by replying to this post, posting a new discussion, or submitting a new issue.

[jshcodes]

⚠️ Reminder ⚠️

The legacy endpoint for this operation will be decommissioned today.

Please make sure you have updated FalconPy to v1.2.0 or greater to make use of the updated endpoints.