/v3/api/sites (GET) - BlueCat Edge - Service Point v3.x.x

BlueCat Edge API Guide

Locale
English
Product name
BlueCat Edge
Version
Service Point v3.x.x

Gets a list of the sites, filtered by query parameters, if specified.

GET https://api-<BlueCat.edge.url>/v3/api/sites
Authorization: Bearer token
Optional query parameters
  • name: (string) filter by the exact name of a site
  • nameContains: (string) filter sites by part of a site name

    The name and nameContains parameters can't be used in the same query.

  • fields: (string, comma separated) fields to include in the response. Example: ?fields=id,name will return a response that contains only the sites' IDs and names.
  • desiredResultCount: (int) the number of sites to include in the response
  • namespaceId: (string) filter sites by a specific namespace ID.
  • overridesForwarders: (boolean) whether to include sites that have overriding forwarders for the specified namespace. Default is false.

    This parameter is only effective when used with the namespaceId parameter.

Successful response

200 OK
Content-Type: application/JSON
[
   {
      "id": "a16a009e-4790-42b6-9374-b1b18e619d76",  
      "name": "Toronto Site",
      "location": {
         "lng": "-79.37566709999999",
         "lat": "43.6421529",
         "address": "4100 Yonge Street, Toronto"                
          },
      "settings": {
          "timeZone":"Australia/Sydney",
          "associatedNamespaces": [ 
               {
                 "id": "5721f5b9-fe9e-11e7-8bf7-0abb5ee73c46",
                 "name": "default",
                 "forwarders": ["8.8.8.8"],
                 "overridingFowarders": [],
                 "description": "This is the default namespace.",
                 "isDefault": true
              }
           ]
        },
        "registeredServicePointCount":10,
        "version": "3.0.6",
        "updateInitiatedTimestamp": 1539180118,
        "updateStatus": "COMPLETED",
        "blockedServicePointIds": [
            "112f2e06-a19d-4775-8aa5-96d997a7b688", 
            "8285cee5-8429-4e23-8970-0233afd312a0", 
            ...
        ],
        "streamDataToCI": true,
        "loggingEndpointId": "123e4567-e89b-12d3-a456-426614174000",
        "loggingEndpointName": "localLoggingEndpoint1"
     },
   ...
]

Service point update details

You can view the software update information that has been configured on all service points that have been deployed from this site. The following fields are associated to the service point update information:
  • version— the current software version that has been configured to run on all service points that have been deployed from this site.
  • updateInitiatedTimestamp— the timestamp of when the service point update selection was confirmed at the site level.
  • updateStatus— the status of the last service point update. The individual update status of each connected service point is cumulatively displayed in this field as follows:
    • COMPLETED - All connected service points deployed from this Site were successfully updated to the service point version configured at the Site.
    • UPDATE_IN_PROGRESS - At least one of the connected service points deployed from this site is updating to the service point version configured at the Site.
    • ROLLING_BACK - At least one of the connected service points deployed from this Site could not successfully update to the service point version configured at the Site and is currently rolling back to the service point version that was running before the update was initiated.
    • ROLLBACK_COMPLETED - At least one of the connected service points deployed from this Site could not successfully update to the service point version configured at the Site and successfully rolled back to the service point version that was running before the update was initiated.
    • FAILED - If at least one of the connected service points deployed from this Site has one of the following issues:
      • The service point could not successfully update to the service point version configured at the Site and was unable to successfully roll back to the service point version that was running before the updated was initiated.
      • The service point returns the TIMED_OUT state.
    • UNKNOWN_STATUS - The service point update status could not be determined across the Site.
    • NO CONNECTED SERVICE POINTS - The service point update was applied to a Site that contains no connected service points.
    Attention:
    • The updateStatus of the site uses the following precedence order based on the statuses returned by the service points:
      • FAILED
      • ROLLING_BACK
      • ROLLBACK_COMPLETED
      • UPDATE_IN_PROGRESS
      • COMPLETED
      • UNKNOWN_STATUS
      • NO CONNECTED SERVICE POINTS
    • A service point returns the TIMED_OUT status when it could not return its update progress to the site within 15 minutes of it starting the service point update. The service point update status will continue to return the TIMED_OUT status until the next attempted update.

      You can review the status of each service point deployed from a site by reviewing the information returned for the site or by reviewing the information returned for the individual service points.

      If your service point returns the TIMED_OUT status:
      • Review the version field of the service point. If the version field of the service point matches the version field of the site, the update applied successfully but the updateStatus was not updated correctly, and no further action is required.
      • If the version field of the service point does not match the version field of the site, retry the service point update. For more information, refer to /v3/api/sites (PATCH).
      • If the connectionState of the service point is Disconnected, review the Cloud access requirements and the connection between the service point and the BlueCat Edge Cloud to ensure that the service point can communicate with the BlueCat Edge Cloud. Once the service point connectionState returns CONNECTED, you can retry the service point update.

      If the issue persists and you can't successfully update the service point, contact BlueCat Customer Care for assistance.

    • If the status of the site updateStatus is ROLLBACK_COMPLETED or FAILED, you can retry the update. For more information, refer to /v3/api/sites (PATCH).
  • blockedServicePointIds—the service points that are blocked from updating. Service points are automatically added to this list if they fail to update.

Custom logging details

You can send all DNS queries from a service point to the BlueCat Edge Cloud console or a local endpoint.
  • streamDataToCI— the boolean that sends DNS queries from a service point to the BlueCat Edge Cloud console. The default value is true.
  • loggingEndpointId— the ID of local logging endpoint.
  • loggingEndpointName— the name of local logging endpoint.
Possible error codes
  • UNAUTHORIZED - Missing or invalid token
  • UNEXPECTED_ERROR
  • BAD_REQUEST
  • ERROR_INVALID_ARGUMENT