19.0 Host Blacklists API

WAS THIS PAGE HELPFUL? Leave Feedback

19.0 Host Blacklists API

19.1 Query Host Blacklists

Retrieve host blacklist records by query. Host blacklists provide a list of host names, (or host name expressions), that are used to filter invalid or disabled hosts. Queries would typically be used to drive administration browsers and similar tooling. Queried host blacklists, (one or more), are always returned wrapped in an XML <hostBlacklists> element or JSON object with an hostBlacklists array member. Getting a single host blacklist record is not wrapped.

19.1.1 Method: GET Host Blacklists

GET /api/hostblacklists?query=(query criteria see below)

19.1.2 Method: GET a Single Host Blacklist by Host Name

GET /api/hostblacklists/{hostName}

19.1.3 HTTP Query and Path Parameters

If neither the hostName path parameter nor query query parameter are provided, all host blacklist records will be retrieved. The first and count paging parameters can be used to avoid excessive retrieval.

19.1.4 HTTP Headers

19.1.5 Query Fields

The table below contains valid fields in the value of the 'query' query parameter.

Note: query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

19.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for first page of all host blacklists
   GET /api/hostblacklists?count=25
2. query for SERVER_2's host blacklist
   GET /api/hostblacklists/SERVER_2
3. query for the second page of host blacklists that start with a prefix, (ordered by hostName)
   GET /api/hostblacklists?query=hostName ilike 'server_%' ORDER BY hostName&first=25&count=25

19.1.7 HTTP Status Codes

19.1.8 Example Query Results

Here is an XML example of the result of a query finding host blacklists.

XML query results are always wrapped in an <hostBlacklists> collection element, with one or more <hostBlacklist> subelements.

<hostBlacklists>
    <hostBlacklist hostBlacklistId="10" hostName="test-host-name-0"/>
    <hostBlacklist hostBlacklistId="11" hostName="test-host-name-1"/>
</hostBlacklists>

Here is a JSON example of the result of a query finding host blacklists.

JSON query results are always wrapped in an object with a hostBlacklists array member, with one or more object members.

{
  "hostBlacklists" : [ {
    "hostBlacklistId" : 12,
    "hostName" : "test-host-name-0"
  }, {
    "hostBlacklistId" : 13,
    "hostName" : "test-host-name-1"
  } ]
}

19.1.9 Example Get Single Results

Here is an XML example of the get host blacklist result.

<hostBlacklist hostBlacklistId="10" hostName="test-host-name-0"/>

Here is a JSON example of the get host blacklist result.

{
  "hostBlacklistId" : 12,
  "hostName" : "test-host-name-0"
}

19.2 Create or Update Host Blacklists

Add or update host blacklists by post. Any number of host blacklists can be posted to the server in a single request. Host blacklist ids will be generated by the server. Requests are considered updates if the host blacklist referenced by the host blacklist id exists. Updates that specify a hostName are assumed to change the host name.

19.2.1 Method: POST Host Blacklists

POST /api/hostblacklists

19.2.2 HTTP Headers

19.2.3 POST Data Example

Here is an XML example post data creating two host blacklists on the server, (the wrapping <hostblacklists> collection element is always required, even for a single host blacklist element):

<hostBlacklists>
    <hostBlacklist hostName="test-host-name-1"/>
    <hostBlacklist hostName="test-host-name-2"/>
</hostBlacklists>

Here is an XML example of post data to update a host blacklist:

<hostBlacklists>
    <hostBlacklist hostBlacklistId="11" hostName="test-host-name-1-changed"/>
</hostBlacklists>

Here is a JSON example post data creating a host blacklist, (the wrapping object with the hostBlacklists array member is always required, even for a single host blacklist object):

{
  "hostBlacklists" : [ {
    "hostName" : "test-host-name-0"
  } ]
}

Here is a JSON example of post data to update a host blacklist:

{
  "hostBlacklists" : [ {
    "hostBlacklistId" : 13,
    "hostName" : "test-host-name-1-changed"
  } ]
}

19.2.4 HTTP Status Codes

19.2.5 Example Responses

Here are XML create responses:

<results successful="2" failed="0" entityType="HostBlacklist" operation="Insert" warning="0" count="2">
    <result><entity>test-host-name-1</entity><message>http://localhost:8080/foundation-webapp/api/hostblacklists/test-host-name-1</message><status>success</status></result>
    <result><entity>test-host-name-2</entity><message>http://localhost:8080/foundation-webapp/api/hostblacklists/test-host-name-2</message><status>success</status></result>
</results>

<results successful="0" failed="1" entityType="HostBlacklist" operation="Insert" warning="0" count="1">
    <result><entity>test-host-name-3</entity><message>Failed to create HostBlacklist: Could not execute JDBC batch update; nested exception is org.hibernate.exception.ConstraintViolationException: Could not execute JDBC batch update</message><status>failure</status></result>
</results>

Here is an XML update response:

<results successful="1" failed="0" entityType="HostBlacklist" operation="Update" warning="0" count="1">
    <result><entity>11</entity><message>http://localhost:8080/foundation-webapp/api/hostblacklists/test-host-name-1-changed</message><status>success</status></result>
</results>

Here are JSON create responses:

{
  "successful" : 2,
  "failed" : 0,
  "entityType" : "HostBlacklist",
  "operation" : "Insert",
  "warning" : 0,
  "results" : [ {
    "entity" : "test-host-name-1",
    "status" : "success",
    "message" : "http://localhost:8080/foundation-webapp/api/hostblacklists/test-host-name-1"
  }, {
    "entity" : "test-host-name-2",
    "status" : "success",
    "message" : "http://localhost:8080/foundation-webapp/api/hostblacklists/test-host-name-2"
  } ],
  "count" : 2
}

{
  "successful" : 0,
  "failed" : 1,
  "entityType" : "HostBlacklist",
  "operation" : "Insert",
  "warning" : 0,
  "results" : [ {
    "entity" : "test-host-name-3",
    "status" : "failure",
    "message" : "Failed to create HostBlacklist: Could not execute JDBC batch update; nested exception is org.hibernate.exception.ConstraintViolationException: Could not execute JDBC batch update"
  } ],
  "count" : 1
}

Here is a JSON update response:

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "HostBlacklist",
  "operation" : "Update",
  "warning" : 0,
  "results" : [ {
    "entity" : "13",
    "status" : "success",
    "message" : "http://localhost:8080/foundation-webapp/api/hostblacklists/test-host-name-1-changed"
  } ],
  "count" : 1
}

19.3 Delete Host Blacklists

Delete host blacklists by delete. Any number of host blacklists can be deleted to the server in a single request. Host blacklist ids or host names must be specified as part of the delete url or body request.

19.3.1 Method: Delete Host Blacklists

DELETE /api/hostblacklists

19.3.2 Method: Delete Host Blacklists by Host Names

DELETE /api/hostblacklists/{hostNames}

19.3.3 HTTP Query and Path Parameters

19.3.4 HTTP Headers

19.3.5 POST Data Example

Here is an XML example post data deleting two host blacklists on the server, (the wrapping <hostblacklists> collection element is always required, even for a single host blacklist element):

<hostBlacklists>
    <hostBlacklist hostBlacklistId="11" hostName="test-host-name-1-changed"/>
    <hostBlacklist hostBlacklistId="12" hostName="test-host-name-2"/>
</hostBlacklists>

Here is a JSON example post data deleting two host blacklists, (the wrapping object with the hostBlacklists array member is always required, even for a single host blacklist object):

{
  "hostBlacklists" : [ {
    "hostBlacklistId" : 13,
    "hostName" : "test-host-name-1-changed"
  },{
    "hostBlacklistId" : 14,
    "hostName" : "test-host-name-2"
  } ]
}

19.3.6 HTTP Status Codes

19.3.7 Example Responses

Here is an XML delete response:

<results successful="2" failed="0" entityType="HostBlacklist" operation="Delete" warning="0" count="2">
    <result><entity>12</entity><message>HostBlacklist deleted</message><status>success</status></result>
    <result><entity>13</entity><message>HostBlacklist deleted</message><status>success</status></result>
</results>

Here is a JSON delete response:

{
  "successful" : 2,
  "failed" : 0,
  "entityType" : "HostBlacklist",
  "operation" : "Delete",
  "warning" : 0,
  "results" : [ {
    "entity" : "13",
    "status" : "success",
    "message" : "HostBlacklist deleted"
  }, {
    "entity" : "14",
    "status" : "success",
    "message" : "HostBlacklist deleted"
  } ],
  "count" : 2
}