Endpoints tutorial

Farsight DNSDB Scout is a graphical user interface (GUI) for the Farsight DNSDB API. Available in all popular web browsers via a website or browser extension, it supports all of the major features of the Farsight DNSDB API.

You can configure Farsight DNSDB Scout to use a specific Farsight DNSDB API server Endpoint. This guide explores all of the available API Endpoint features.

Setting an API endpoint

By default, Farsight DNSDB Scout uses the primary Farsight DNSDB API host, api.dnsdb.info.

Private deployments of Farsight DNSDB Scout for Export may use a different API Endpoint by default, but you can always change it locally within your web browser.

To change your API Endpoint, first go to the Options page. Access the Options page via the ‘gear’ icon in the top right corner.

Options page gear icon in the top-right corner

Open the Advanced section of the page. Within the Advanced section is a subsection dedicated to all API Endpoint related settings.

Advanced section showing the API Endpoint settings

The currently set API Endpoint appears pre-filled in the field. Enter a different API Endpoint host and then click the Save Endpoint button to set it.

The protocol for an API Endpoint is always https and cannot be changed. If you leave the field empty when clicking the Save Endpoint button, it defaults to api.dnsdb.info or a different preset if you use a Farsight DNSDB Scout for Export instance.

API Endpoint field with the Save Endpoint button

When you save the API Endpoint, Farsight DNSDB Scout performs a connection and quota check. If any problems occur when reaching the new API Endpoint, they appear at the top of the screen in the connection and quota display area.

Connection and quota check display after saving an Endpoint

If no issues occur when reaching the new API Endpoint, your normal quota information appears and you can start making Farsight DNSDB queries on the main Dashboard.

Farsight DNSDB export mode

You can use Farsight DNSDB Scout with Farsight DNSDB Export instances, and you can even deploy it as Farsight DNSDB Scout for Export with a preconfigured API Endpoint for a specific Farsight DNSDB Export instance.

To switch Farsight DNSDB Scout’s Export Mode either check or uncheck the Farsight DNSDB Export Instance option within the API Endpoint settings and then click the Save Endpoint button.

Farsight DNSDB Export Instance option in the API Endpoint settings

Note: Some Farsight DNSDB Export instances may only support APIv1, while others may only support APIv2. Additionally, your Farsight DNSDB Export instance may only be accessible while on certain networks. Please check with your Export instance operator regarding API versioning and provisioned access.

Troubleshooting Export endpoint connection errors

If saving the endpoint produces a connection or quota error in the display area at the top of the screen, the API Endpoint is most often pointed at the wrong host. Export hostnames can change between provisioning stages, so an endpoint that worked before may no longer be valid.

To resolve it:

1. Confirm the current endpoint hostname with your Export instance operator.
2. On the Options page, open the Advanced section and enter that hostname in the API Endpoint field. Enter the hostname only; the https protocol is assumed.
3. Click Save Endpoint. Scout re-runs the connection and quota check against the new host.

If the error persists after confirming the hostname, verify that you’re on a network permitted to reach the instance and that you’re using the API version your operator supports.

Setting a different API version

Farsight DNSDB Scout supports both of the currently available Farsight DNSDB API versions, v1 and v2. By default, most versions of Farsight DNSDB Scout will use v2.

Broadly, v1 lacks Flexible Search and additional improvements made by the SAF Protocol used by v2. Responses from v1 servers differ slightly from those from v2 servers. Some Farsight DNSDB API servers only support v1, so you need to switch Farsight DNSDB Scout to v1 mode to use those servers.

If you are using api.dnsdb.info as your API Endpoint then v2 is strongly encouraged over v1.

For more details about the differences between APIv1 and APIv2 please refer to the Farsight DNSDB API Documentation.

To switch Farsight DNSDB Scout to v1 mode select the APIv1 radio option within the API Endpoint settings and then click the Save Endpoint button.

APIv1 radio option in the API Endpoint settings

You can switch Farsight DNSDB Scout back to v2 mode by selecting the APIv2 option and re-saving your API Endpoint settings.