WAS THIS PAGE HELPFUL? {html}<a href="mailto:training@gwos.com?subject=Host Identity APIs">Leave Feedback</a>{html}
h4. 18.0 Host Identities APIs
h5. 18.1 Query Host Identities
Retrieve host identity records by query. Host identities provide a mapping between a UUID key and a set of alternate host names and a host. Queries would typically be used to drive administration browsers and similar tooling. Queried host identities, (one or more), are always returned wrapped in an XML {{<hostIdentities>}} element or JSON object with an {{hostIdentities}} array member. Getting a single host identity record is not wrapped.
h6. {color:#333333}18.1.1 Method: GET Host Identities{color}
{color:#4a86e8}GET /api/hostidentities?query=(query criteria see below){color}
h6. {color:#333333}18.1.2 Method: GET a Single Host Identity by Id or Host Name{color}
{color:#4a86e8}GET /api/hostidentities/\{idOrHostName\}{color}
h6. {color:#333333}18.1.3 HTTP Query and Path Parameters{color}
|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no |
| first | Query | Paging, first record to start from | no |
| count | Query | Paging, the number of records to include when paging | no |
| idOrHostName | Path | the id or host name to retrieve, (case insensitive) | yes |
_If neither the idOrHostName path parameter nor query query parameter are provided, all host identity records will be retrieved. The first and count paging parameters can be used to avoid excessive retrieval._
h6. {color:#333333}18.1.4 HTTP Headers{color}
|| Header || Valid Values || Required ||
| Accept | application/xml or application/json | False |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. {color:#333333}18.1.5 Query Fields{color}
{color:#000000}The table below contains valid fields in the value of the 'query' query parameter.{color}
|| Field || Description || Alias ||
| hostIdentityId | primary UUID key | id |
| hostName | primary/host host name | |
| hostNames | alternate host names, (also contains hostName) | |
| host | host the host identity is associated with | |
Note: query fields are case-insensitive, thus camelCase, or all lower case will both work fine.
h6. {color:#333333}18.1.6 Example Queries{color}
_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# {color:#000000}{_}query for first page of all host identities{_}{color}
{color:#4a86e8}GET /api/hostidentities?count=25{color}
# {color:#000000}{_}query for SERVER_2's host identity{_}{color}
{color:#4a86e8}GET /api/hostidentities/SERVER_2{color}
# {color:#000000}{_}query for the second page of host identities that start with a prefix, (ordered by hostName)_{color}
{color:#4a86e8}GET /api/hostidentities?query=hostNames.id ilike 'server_%' ORDER BY hostName&first=25&count=25{color}
h6. {color:#333333}18.1.7 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Query returned no host identities |
| 200 | Query returned one or more host identities |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while querying host identities |
h6. {color:#333333}18.1.8 Example Query Results{color}
Here is an XML example of the result of a query finding host identities.
XML query results are always wrapped in an {{<hostIdentities>}} collection element, with one or more {{<hostIdentity>}} subelements.
{code: language=html/xml}
<hostIdentities>
<hostIdentity hostIdentityId="11c2d250-6437-11e4-9584-002219ed08d3" hostName="test-host-name-0" host="false"><hostNames><hostName>test-host-name-0</hostName></hostNames></hostIdentity>
<hostIdentity hostIdentityId="12042cdc-6437-11e4-9585-002219ed08d3" hostName="test-host-name-1" host="false"><hostNames><hostName>test-host-name-1</hostName><hostName>test-host-name-1.0</hostName><hostName>test-host-name-1.1</hostName></hostNames></hostIdentity>
</hostIdentities>
{code}
Here is a JSON example of the result of a query finding host identities.
JSON query results are always wrapped in an object with a {{hostIdentities}} array member, with one or more object members.
{code: language=javascript}
{
"hostIdentities" : [ {
"hostIdentityId" : "1267adf2-6437-11e4-82be-002219ed08d3",
"hostName" : "test-host-name-0",
"hostNames" : [ "test-host-name-0" ],
"host" : false
}, {
"hostIdentityId" : "12c545e8-6437-11e4-82bf-002219ed08d3",
"hostName" : "test-host-name-1",
"hostNames" : [ "test-host-name-1", "test-host-name-1.0", "test-host-name-1.1" ],
"host" : false
} ]
}
{code}
h6. {color:#333333}18.1.9 Example Get Single Results{color}
Here is an XML example of the get host identity result.
{code: language=html/xml}
<hostIdentity hostIdentityId="11c2d250-6437-11e4-9584-002219ed08d3" hostName="test-host-name-0" host="false"><hostNames><hostName>test-host-name-0</hostName></hostNames></hostIdentity>
{code}
Here is a JSON example of the get host identity result.
{code: language=javascript}
{
"hostIdentityId" : "1267adf2-6437-11e4-82be-002219ed08d3",
"hostName" : "test-host-name-0",
"hostNames" : [ "test-host-name-0" ],
"host" : false
}
{code}
h5. {color:#333333}18.2 Create or Update Host Identities{color}
Add or update host identities by post. Any number of host identities can be posted to the server in a single asynchronous, (the default), or synchronous request. Host identity ids will be defaulted by the server, but they can be specified as part of the post body request. Requests are considered updates if the host identity referenced by id or primary host name exists. Updates that specify a hostName are assumed to rename the host identity and associated host. If the update specifies hostNames, these are added as new alternate host names. The delete/clear request documented below can be used to remove all hostNames.
h6. {color:#333333}18.2.1 Method: POST Host Identities{color}
{color:#4a86e8}POST /api/hostidentities{color}
h6. {color:#333333}18.2.2 HTTP Query Parameters{color}
|| Field || Description || Required ||
| async | A boolean flag to indicate whether to submit the batch of host identity inserts and/or updates asynchronously or not. Default is false. Valid values are true or false. A synchronous request will not return back to your client code until the completion of processing all objects provided in the post data. Whereas an asynchronous request will submit the work to a queue, and return immediately. | False |
h6. {color:#333333}18.2.3 HTTP Headers{color}
|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| Accept | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. {color:#333333}18.2.4 POST Data Example{color}
Here is an XML example post data creating two host identities on the server, (the wrapping {{<hostidentities>}} collection element is always required, even for a single host identity element):
{code: language=html/xml}
<hostIdentities>
<hostIdentity hostName="test-host-name-1"><hostNames><hostName>test-host-name-1.0</hostName><hostName>test-host-name-1.1</hostName><hostName>test-host-name-1</hostName></hostNames></hostIdentity>
<hostIdentity hostIdentityId="5d33537c-293e-4564-b0cf-d0998389b31f" hostName="test-host-name-2"><hostNames><hostName>46eb4a5b-a08e-470b-9be7-8108aa5a2cc7</hostName><hostName>test-host-name-2</hostName></hostNames></hostIdentity>
</hostIdentities>
{code}
Here is an XML example of post data to update a host identity:
{code: language=html/xml}
<hostIdentities>
<hostIdentity hostIdentityId="12042cdc-6437-11e4-9585-002219ed08d3" hostName="test-host-name-1-changed"><hostNames><hostName>test-host-name-1-changed-alias</hostName></hostNames></hostIdentity>
</hostIdentities>
{code}
Here is a JSON example post data creating a host identity, (the wrapping object with the {{hostIdentities}} array member is always required, even for a single host identity object):
{code: language=javascript}
{
"hostIdentities":[{
"hostName":"test-host-name-0",
"hostNames":["test-host-name-0"]
}]
}
{code}
Here is a JSON example of post data to update a host identity:
{code: language=javascript}
{
"hostIdentities":[{
"hostIdentityId":"12c545e8-6437-11e4-82bf-002219ed08d3",
"hostName":"test-host-name-1-changed",
"hostNames":["test-host-name-1-changed-alias"]
}]
}
{code}
h6. {color:#333333}18.2.5 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Zero or more host identities were created synchronously or an asynchronous create started |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while creating host identities or starting an asynchronous create |
h6. {color:#333333}18.2.6 Example Responses{color}
Here are XML asynchronous and synchronous create responses:
{code: language=html/xml}
<results successful="1" failed="0" entityType="HostIdentity Async" operation="Insert" warning="0" count="1">
<result><entity>1415114840770</entity><message>Job 1415114840770 submitted</message><status>success</status></result>
</results>
{code}
{code: language=html/xml}
<results successful="2" failed="0" entityType="HostIdentity" operation="Insert" warning="0" count="2">
<result><entity>test-host-name-1</entity><message>http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-1</message><status>success</status></result>
<result><entity>test-host-name-2</entity><message>http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-2</message><status>success</status></result>
</results>
{code}
{code: language=html/xml}
<results successful="0" failed="1" entityType="HostIdentity" operation="Insert" warning="0" count="1">
<result><entity>test-host-name-3</entity><message>Failed to create HostIdentity: 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>
{code}
Here is an XML synchronous update response:
{code: language=html/xml}
<results successful="1" failed="0" entityType="HostIdentity" operation="Update" warning="0" count="1">
<result><entity>12042cdc-6437-11e4-9585-002219ed08d3</entity><message>http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-1-changed</message><status>success</status></result>
</results>
{code}
Here are JSON asynchronous and synchronous create responses:
{code: language=javascript}
{
"successful" : 1,
"failed" : 0,
"entityType" : "HostIdentity Async",
"operation" : "Insert",
"warning" : 0,
"results" : [ {
"entity" : "1415114842259",
"status" : "success",
"message" : "Job 1415114842259 submitted"
} ],
"count" : 1
}
{code}
{code: language=javascript}
{
"successful" : 2,
"failed" : 0,
"entityType" : "HostIdentity",
"operation" : "Insert",
"warning" : 0,
"results" : [ {
"entity" : "test-host-name-1",
"status" : "success",
"message" : "http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-1"
}, {
"entity" : "test-host-name-2",
"status" : "success",
"message" : "http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-2"
} ],
"count" : 2
}
{code}
{code: language=javascript}
{
"successful" : 0,
"failed" : 1,
"entityType" : "HostIdentity",
"operation" : "Insert",
"warning" : 0,
"results" : [ {
"entity" : "test-host-name-3",
"status" : "failure",
"message" : "Failed to create HostIdentity: Could not execute JDBC batch update; nested exception is org.hibernate.exception.ConstraintViolationException: Could not execute JDBC batch update"
} ],
"count" : 1
}
{code}
Here is a JSON synchronous update response:
{code: language=javascript}
{
"successful" : 1,
"failed" : 0,
"entityType" : "HostIdentity",
"operation" : "Update",
"warning" : 0,
"results" : [ {
"entity" : "12c545e8-6437-11e4-82bf-002219ed08d3",
"status" : "success",
"message" : "http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-1-changed"
} ],
"count" : 1
}
{code}
h5. {color:#333333}18.3 Delete or Clear Host Identities{color}
Delete host identities or clear host identities host names by delete. Any number of host identities can be deleted to the server in a single request. Host identity ids or primary host names must be specified as part of the delete url or body request.
h6. {color:#333333}18.3.1 Method: Delete Host Identities{color}
{color:#4a86e8}DELETE /api/hostidentities{color}
h6. {color:#333333}18.3.2 Method: Delete Host Identities by Id or Host Names{color}
{color:#4a86e8}DELETE /api/hostidentities/\{idOrHostNames\}{color}
h6. {color:#333333}18.3.3 HTTP Query and Path Parameters{color}
|| Field || Type || Description || Required ||
| clear | Query | A boolean flag to indicate whether the host identities host names should be cleared or if the host identities should be deleted. Default is false, (delete host identities). Valid values are true or false. | False |
| idOrHostNames | Path | list of ids or host names to retrieve, (case insensitive, comma separated list) | True |
h6. {color:#333333}18.3.4 HTTP Headers{color}
|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| Accept | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. {color:#333333}18.3.5 POST Data Example{color}
Here is an XML example post data deleting or clearing two host identities on the server, (the wrapping {{<hostidentities>}} collection element is always required, even for a single host identity element):
{code: language=html/xml}
<hostIdentities>
<hostIdentity hostIdentityId="12042cdc-6437-11e4-9585-002219ed08d3" hostName="test-host-name-1-changed"><hostNames><hostName>test-host-name-1</hostName><hostName>test-host-name-1-changed</hostName><hostName>test-host-name-1-changed-alias</hostName></hostNames></hostIdentity>
<hostIdentity hostIdentityId="5d33537c-293e-4564-b0cf-d0998389b31f" hostName="test-host-name-2"><hostNames><hostName>test-host-name-2</hostName><hostName>46eb4a5b-a08e-470b-9be7-8108aa5a2cc7</hostName></hostNames></hostIdentity>
</hostIdentities>
{code}
Here is a JSON example post data deleting or clearing two host identities, (the wrapping object with the {{hostIdentities}} array member is always required, even for a single host identity object):
{code: language=javascript}
{
"hostIdentities" : [ {
"hostIdentityId" : "12c545e8-6437-11e4-82bf-002219ed08d3",
"hostName" : "test-host-name-1-changed",
"hostNames" : ["test-host-name-1","test-host-name-1-changed","test-host-name-1-changed-alias"]
},{
"hostIdentityId" : "8fb9a880-f093-4892-a0f3-b1a403b49e5e",
"hostName" : "test-host-name-2",
"hostNames" : ["test-host-name-2","9e1b25a0-e036-4ce1-bf01-56c9cc8934ce"]
} ]
}
{code}
h6. {color:#333333}18.3.6 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Zero or more host identities were deleted or cleared successfully |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while creating host identities or starting an asynchronous create |
h6. {color:#333333}18.3.7 Example Responses{color}
Here are XML clear and delete responses:
{code: language=html/xml}
<results successful="1" failed="0" entityType="HostIdentity" operation="Clear" warning="0" count="1">
<result><entity>test-host-name-1</entity><message>HostIdentity cleared</message><status>success</status></result>
</results>
{code}
{code: language=html/xml}
<results successful="2" failed="0" entityType="HostIdentity" operation="Delete" warning="0" count="2">
<result><entity>12042cdc-6437-11e4-9585-002219ed08d3</entity><message>HostIdentity deleted</message><status>success</status></result>
<result><entity>5d33537c-293e-4564-b0cf-d0998389b31f</entity><message>HostIdentity deleted</message><status>success</status></result>
</results>
{code}
Here are JSON clear and delete responses:
{code: language=javascript}
{
"successful" : 1,
"failed" : 0,
"entityType" : "HostIdentity",
"operation" : "Clear",
"warning" : 0,
"results" : [ {
"entity" : "test-host-name-1",
"status" : "success",
"message" : "HostIdentity cleared"
} ],
"count" : 1
}
{code}
{code: language=javascript}
{
"successful" : 2,
"failed" : 0,
"entityType" : "HostIdentity",
"operation" : "Delete",
"warning" : 0,
"results" : [ {
"entity" : "12c545e8-6437-11e4-82bf-002219ed08d3",
"status" : "success",
"message" : "HostIdentity deleted"
}, {
"entity" : "8fb9a880-f093-4892-a0f3-b1a403b49e5e",
"status" : "success",
"message" : "HostIdentity deleted"
} ],
"count" : 2
}
{code}
h5. {color:#333333}18.4 Host Identity Host Name Autocomplete{color}
Get limited number of sorted existing Host Identity and Host host names that match a specified prefix. Matching and sorting is done in a case-insensitive fashion. The special wildcard prefix '*' matches all names. Autocomplete names are updated asynchronously when Host Identities or Hosts host names are modified.
h6. {color:#333333}18.4.1 Method: GET Host Identity Host Name Autocomplete{color}
{color:#4a86e8}GET /api/hostidentities/autocomplete/\{prefix\}{color}
h6. {color:#333333}18.4.2 Path Parameters{color}
|| Field || Type || Description || Required ||
| prefix | Path | Encoded Host Identity or Host host names prefix to match | yes |
h6. {color:#333333}18.4.3 HTTP Headers{color}
|| Header || Valid Values || Required ||
| Accept | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. {color:#333333}18.4.4 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Autocomplete names for prefix returned |
| 404 | No autocomplete names for prefix |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while processing autocomplete prefix |
h6. {color:#333333}18.4.5 Example Responses{color}
Here is an XML example of the autocomplete names returned.
XML results are always wrapped in an {{<names>}} collection element, with one or more {{<name>}} subelements.
{code: language=html/xml}
<names>
<name>localhost</name>
<name>localhost2</name>
</names>
{code}
Here is a JSON example of the autocomplete returned.
JSON results are always wrapped in an object with a {{names}} array member, with one or more name strings.
{code: language=javascript}
{
"names" : [ "localhost", "localhost2" ]
}
{code}
h4. 18.0 Host Identities APIs
h5. 18.1 Query Host Identities
Retrieve host identity records by query. Host identities provide a mapping between a UUID key and a set of alternate host names and a host. Queries would typically be used to drive administration browsers and similar tooling. Queried host identities, (one or more), are always returned wrapped in an XML {{<hostIdentities>}} element or JSON object with an {{hostIdentities}} array member. Getting a single host identity record is not wrapped.
h6. {color:#333333}18.1.1 Method: GET Host Identities{color}
{color:#4a86e8}GET /api/hostidentities?query=(query criteria see below){color}
h6. {color:#333333}18.1.2 Method: GET a Single Host Identity by Id or Host Name{color}
{color:#4a86e8}GET /api/hostidentities/\{idOrHostName\}{color}
h6. {color:#333333}18.1.3 HTTP Query and Path Parameters{color}
|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no |
| first | Query | Paging, first record to start from | no |
| count | Query | Paging, the number of records to include when paging | no |
| idOrHostName | Path | the id or host name to retrieve, (case insensitive) | yes |
_If neither the idOrHostName path parameter nor query query parameter are provided, all host identity records will be retrieved. The first and count paging parameters can be used to avoid excessive retrieval._
h6. {color:#333333}18.1.4 HTTP Headers{color}
|| Header || Valid Values || Required ||
| Accept | application/xml or application/json | False |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. {color:#333333}18.1.5 Query Fields{color}
{color:#000000}The table below contains valid fields in the value of the 'query' query parameter.{color}
|| Field || Description || Alias ||
| hostIdentityId | primary UUID key | id |
| hostName | primary/host host name | |
| hostNames | alternate host names, (also contains hostName) | |
| host | host the host identity is associated with | |
Note: query fields are case-insensitive, thus camelCase, or all lower case will both work fine.
h6. {color:#333333}18.1.6 Example Queries{color}
_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# {color:#000000}{_}query for first page of all host identities{_}{color}
{color:#4a86e8}GET /api/hostidentities?count=25{color}
# {color:#000000}{_}query for SERVER_2's host identity{_}{color}
{color:#4a86e8}GET /api/hostidentities/SERVER_2{color}
# {color:#000000}{_}query for the second page of host identities that start with a prefix, (ordered by hostName)_{color}
{color:#4a86e8}GET /api/hostidentities?query=hostNames.id ilike 'server_%' ORDER BY hostName&first=25&count=25{color}
h6. {color:#333333}18.1.7 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Query returned no host identities |
| 200 | Query returned one or more host identities |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while querying host identities |
h6. {color:#333333}18.1.8 Example Query Results{color}
Here is an XML example of the result of a query finding host identities.
XML query results are always wrapped in an {{<hostIdentities>}} collection element, with one or more {{<hostIdentity>}} subelements.
{code: language=html/xml}
<hostIdentities>
<hostIdentity hostIdentityId="11c2d250-6437-11e4-9584-002219ed08d3" hostName="test-host-name-0" host="false"><hostNames><hostName>test-host-name-0</hostName></hostNames></hostIdentity>
<hostIdentity hostIdentityId="12042cdc-6437-11e4-9585-002219ed08d3" hostName="test-host-name-1" host="false"><hostNames><hostName>test-host-name-1</hostName><hostName>test-host-name-1.0</hostName><hostName>test-host-name-1.1</hostName></hostNames></hostIdentity>
</hostIdentities>
{code}
Here is a JSON example of the result of a query finding host identities.
JSON query results are always wrapped in an object with a {{hostIdentities}} array member, with one or more object members.
{code: language=javascript}
{
"hostIdentities" : [ {
"hostIdentityId" : "1267adf2-6437-11e4-82be-002219ed08d3",
"hostName" : "test-host-name-0",
"hostNames" : [ "test-host-name-0" ],
"host" : false
}, {
"hostIdentityId" : "12c545e8-6437-11e4-82bf-002219ed08d3",
"hostName" : "test-host-name-1",
"hostNames" : [ "test-host-name-1", "test-host-name-1.0", "test-host-name-1.1" ],
"host" : false
} ]
}
{code}
h6. {color:#333333}18.1.9 Example Get Single Results{color}
Here is an XML example of the get host identity result.
{code: language=html/xml}
<hostIdentity hostIdentityId="11c2d250-6437-11e4-9584-002219ed08d3" hostName="test-host-name-0" host="false"><hostNames><hostName>test-host-name-0</hostName></hostNames></hostIdentity>
{code}
Here is a JSON example of the get host identity result.
{code: language=javascript}
{
"hostIdentityId" : "1267adf2-6437-11e4-82be-002219ed08d3",
"hostName" : "test-host-name-0",
"hostNames" : [ "test-host-name-0" ],
"host" : false
}
{code}
h5. {color:#333333}18.2 Create or Update Host Identities{color}
Add or update host identities by post. Any number of host identities can be posted to the server in a single asynchronous, (the default), or synchronous request. Host identity ids will be defaulted by the server, but they can be specified as part of the post body request. Requests are considered updates if the host identity referenced by id or primary host name exists. Updates that specify a hostName are assumed to rename the host identity and associated host. If the update specifies hostNames, these are added as new alternate host names. The delete/clear request documented below can be used to remove all hostNames.
h6. {color:#333333}18.2.1 Method: POST Host Identities{color}
{color:#4a86e8}POST /api/hostidentities{color}
h6. {color:#333333}18.2.2 HTTP Query Parameters{color}
|| Field || Description || Required ||
| async | A boolean flag to indicate whether to submit the batch of host identity inserts and/or updates asynchronously or not. Default is false. Valid values are true or false. A synchronous request will not return back to your client code until the completion of processing all objects provided in the post data. Whereas an asynchronous request will submit the work to a queue, and return immediately. | False |
h6. {color:#333333}18.2.3 HTTP Headers{color}
|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| Accept | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. {color:#333333}18.2.4 POST Data Example{color}
Here is an XML example post data creating two host identities on the server, (the wrapping {{<hostidentities>}} collection element is always required, even for a single host identity element):
{code: language=html/xml}
<hostIdentities>
<hostIdentity hostName="test-host-name-1"><hostNames><hostName>test-host-name-1.0</hostName><hostName>test-host-name-1.1</hostName><hostName>test-host-name-1</hostName></hostNames></hostIdentity>
<hostIdentity hostIdentityId="5d33537c-293e-4564-b0cf-d0998389b31f" hostName="test-host-name-2"><hostNames><hostName>46eb4a5b-a08e-470b-9be7-8108aa5a2cc7</hostName><hostName>test-host-name-2</hostName></hostNames></hostIdentity>
</hostIdentities>
{code}
Here is an XML example of post data to update a host identity:
{code: language=html/xml}
<hostIdentities>
<hostIdentity hostIdentityId="12042cdc-6437-11e4-9585-002219ed08d3" hostName="test-host-name-1-changed"><hostNames><hostName>test-host-name-1-changed-alias</hostName></hostNames></hostIdentity>
</hostIdentities>
{code}
Here is a JSON example post data creating a host identity, (the wrapping object with the {{hostIdentities}} array member is always required, even for a single host identity object):
{code: language=javascript}
{
"hostIdentities":[{
"hostName":"test-host-name-0",
"hostNames":["test-host-name-0"]
}]
}
{code}
Here is a JSON example of post data to update a host identity:
{code: language=javascript}
{
"hostIdentities":[{
"hostIdentityId":"12c545e8-6437-11e4-82bf-002219ed08d3",
"hostName":"test-host-name-1-changed",
"hostNames":["test-host-name-1-changed-alias"]
}]
}
{code}
h6. {color:#333333}18.2.5 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Zero or more host identities were created synchronously or an asynchronous create started |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while creating host identities or starting an asynchronous create |
h6. {color:#333333}18.2.6 Example Responses{color}
Here are XML asynchronous and synchronous create responses:
{code: language=html/xml}
<results successful="1" failed="0" entityType="HostIdentity Async" operation="Insert" warning="0" count="1">
<result><entity>1415114840770</entity><message>Job 1415114840770 submitted</message><status>success</status></result>
</results>
{code}
{code: language=html/xml}
<results successful="2" failed="0" entityType="HostIdentity" operation="Insert" warning="0" count="2">
<result><entity>test-host-name-1</entity><message>http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-1</message><status>success</status></result>
<result><entity>test-host-name-2</entity><message>http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-2</message><status>success</status></result>
</results>
{code}
{code: language=html/xml}
<results successful="0" failed="1" entityType="HostIdentity" operation="Insert" warning="0" count="1">
<result><entity>test-host-name-3</entity><message>Failed to create HostIdentity: 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>
{code}
Here is an XML synchronous update response:
{code: language=html/xml}
<results successful="1" failed="0" entityType="HostIdentity" operation="Update" warning="0" count="1">
<result><entity>12042cdc-6437-11e4-9585-002219ed08d3</entity><message>http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-1-changed</message><status>success</status></result>
</results>
{code}
Here are JSON asynchronous and synchronous create responses:
{code: language=javascript}
{
"successful" : 1,
"failed" : 0,
"entityType" : "HostIdentity Async",
"operation" : "Insert",
"warning" : 0,
"results" : [ {
"entity" : "1415114842259",
"status" : "success",
"message" : "Job 1415114842259 submitted"
} ],
"count" : 1
}
{code}
{code: language=javascript}
{
"successful" : 2,
"failed" : 0,
"entityType" : "HostIdentity",
"operation" : "Insert",
"warning" : 0,
"results" : [ {
"entity" : "test-host-name-1",
"status" : "success",
"message" : "http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-1"
}, {
"entity" : "test-host-name-2",
"status" : "success",
"message" : "http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-2"
} ],
"count" : 2
}
{code}
{code: language=javascript}
{
"successful" : 0,
"failed" : 1,
"entityType" : "HostIdentity",
"operation" : "Insert",
"warning" : 0,
"results" : [ {
"entity" : "test-host-name-3",
"status" : "failure",
"message" : "Failed to create HostIdentity: Could not execute JDBC batch update; nested exception is org.hibernate.exception.ConstraintViolationException: Could not execute JDBC batch update"
} ],
"count" : 1
}
{code}
Here is a JSON synchronous update response:
{code: language=javascript}
{
"successful" : 1,
"failed" : 0,
"entityType" : "HostIdentity",
"operation" : "Update",
"warning" : 0,
"results" : [ {
"entity" : "12c545e8-6437-11e4-82bf-002219ed08d3",
"status" : "success",
"message" : "http://localhost:8080/foundation-webapp/api/hostidentities/test-host-name-1-changed"
} ],
"count" : 1
}
{code}
h5. {color:#333333}18.3 Delete or Clear Host Identities{color}
Delete host identities or clear host identities host names by delete. Any number of host identities can be deleted to the server in a single request. Host identity ids or primary host names must be specified as part of the delete url or body request.
h6. {color:#333333}18.3.1 Method: Delete Host Identities{color}
{color:#4a86e8}DELETE /api/hostidentities{color}
h6. {color:#333333}18.3.2 Method: Delete Host Identities by Id or Host Names{color}
{color:#4a86e8}DELETE /api/hostidentities/\{idOrHostNames\}{color}
h6. {color:#333333}18.3.3 HTTP Query and Path Parameters{color}
|| Field || Type || Description || Required ||
| clear | Query | A boolean flag to indicate whether the host identities host names should be cleared or if the host identities should be deleted. Default is false, (delete host identities). Valid values are true or false. | False |
| idOrHostNames | Path | list of ids or host names to retrieve, (case insensitive, comma separated list) | True |
h6. {color:#333333}18.3.4 HTTP Headers{color}
|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| Accept | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. {color:#333333}18.3.5 POST Data Example{color}
Here is an XML example post data deleting or clearing two host identities on the server, (the wrapping {{<hostidentities>}} collection element is always required, even for a single host identity element):
{code: language=html/xml}
<hostIdentities>
<hostIdentity hostIdentityId="12042cdc-6437-11e4-9585-002219ed08d3" hostName="test-host-name-1-changed"><hostNames><hostName>test-host-name-1</hostName><hostName>test-host-name-1-changed</hostName><hostName>test-host-name-1-changed-alias</hostName></hostNames></hostIdentity>
<hostIdentity hostIdentityId="5d33537c-293e-4564-b0cf-d0998389b31f" hostName="test-host-name-2"><hostNames><hostName>test-host-name-2</hostName><hostName>46eb4a5b-a08e-470b-9be7-8108aa5a2cc7</hostName></hostNames></hostIdentity>
</hostIdentities>
{code}
Here is a JSON example post data deleting or clearing two host identities, (the wrapping object with the {{hostIdentities}} array member is always required, even for a single host identity object):
{code: language=javascript}
{
"hostIdentities" : [ {
"hostIdentityId" : "12c545e8-6437-11e4-82bf-002219ed08d3",
"hostName" : "test-host-name-1-changed",
"hostNames" : ["test-host-name-1","test-host-name-1-changed","test-host-name-1-changed-alias"]
},{
"hostIdentityId" : "8fb9a880-f093-4892-a0f3-b1a403b49e5e",
"hostName" : "test-host-name-2",
"hostNames" : ["test-host-name-2","9e1b25a0-e036-4ce1-bf01-56c9cc8934ce"]
} ]
}
{code}
h6. {color:#333333}18.3.6 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Zero or more host identities were deleted or cleared successfully |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while creating host identities or starting an asynchronous create |
h6. {color:#333333}18.3.7 Example Responses{color}
Here are XML clear and delete responses:
{code: language=html/xml}
<results successful="1" failed="0" entityType="HostIdentity" operation="Clear" warning="0" count="1">
<result><entity>test-host-name-1</entity><message>HostIdentity cleared</message><status>success</status></result>
</results>
{code}
{code: language=html/xml}
<results successful="2" failed="0" entityType="HostIdentity" operation="Delete" warning="0" count="2">
<result><entity>12042cdc-6437-11e4-9585-002219ed08d3</entity><message>HostIdentity deleted</message><status>success</status></result>
<result><entity>5d33537c-293e-4564-b0cf-d0998389b31f</entity><message>HostIdentity deleted</message><status>success</status></result>
</results>
{code}
Here are JSON clear and delete responses:
{code: language=javascript}
{
"successful" : 1,
"failed" : 0,
"entityType" : "HostIdentity",
"operation" : "Clear",
"warning" : 0,
"results" : [ {
"entity" : "test-host-name-1",
"status" : "success",
"message" : "HostIdentity cleared"
} ],
"count" : 1
}
{code}
{code: language=javascript}
{
"successful" : 2,
"failed" : 0,
"entityType" : "HostIdentity",
"operation" : "Delete",
"warning" : 0,
"results" : [ {
"entity" : "12c545e8-6437-11e4-82bf-002219ed08d3",
"status" : "success",
"message" : "HostIdentity deleted"
}, {
"entity" : "8fb9a880-f093-4892-a0f3-b1a403b49e5e",
"status" : "success",
"message" : "HostIdentity deleted"
} ],
"count" : 2
}
{code}
h5. {color:#333333}18.4 Host Identity Host Name Autocomplete{color}
Get limited number of sorted existing Host Identity and Host host names that match a specified prefix. Matching and sorting is done in a case-insensitive fashion. The special wildcard prefix '*' matches all names. Autocomplete names are updated asynchronously when Host Identities or Hosts host names are modified.
h6. {color:#333333}18.4.1 Method: GET Host Identity Host Name Autocomplete{color}
{color:#4a86e8}GET /api/hostidentities/autocomplete/\{prefix\}{color}
h6. {color:#333333}18.4.2 Path Parameters{color}
|| Field || Type || Description || Required ||
| prefix | Path | Encoded Host Identity or Host host names prefix to match | yes |
h6. {color:#333333}18.4.3 HTTP Headers{color}
|| Header || Valid Values || Required ||
| Accept | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. {color:#333333}18.4.4 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Autocomplete names for prefix returned |
| 404 | No autocomplete names for prefix |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while processing autocomplete prefix |
h6. {color:#333333}18.4.5 Example Responses{color}
Here is an XML example of the autocomplete names returned.
XML results are always wrapped in an {{<names>}} collection element, with one or more {{<name>}} subelements.
{code: language=html/xml}
<names>
<name>localhost</name>
<name>localhost2</name>
</names>
{code}
Here is a JSON example of the autocomplete returned.
JSON results are always wrapped in an object with a {{names}} array member, with one or more name strings.
{code: language=javascript}
{
"names" : [ "localhost", "localhost2" ]
}
{code}