This topic explains how to make API calls with Qualys APIs.
We use curl in our API documentation to show an example of how to form REST API calls, and it is not meant to be an actual production example of implementation.
While it is still possible to create simple API requests using the GET method, you can create API requests using the POST method with an XML payload to make an advanced request.
The XML payloads can be compared to a scripting language that allows users to make multiple actions within one single API request, like adding a parameter to an object and updating another parameter.
The XML structure of the payload is described in the XSD files.
The XML output of a search API request is paginated and the default page size is 100 object records. The page size can be customized to a value between 1 and 1,000. If the number of records is greater than the page size then the <ServiceResponse> element shows the response code SUCCESS with the element <hasMoreRecords>true</hasMoreRecords> as shown below.
Follow the process below to obtain the first two XML pages for an API request. Apply the same logic to get all the next (n+1) pages until all records are returned. This is indicated when <hasMoreRecords>false</hasMoreRecords>.
Search for web applications that have a name containing the string “Merchant.” The service request in the POST data file “file.xml” defines these search criteria.
API request
curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST"
--data-binary @-"<qualys_base_url>/qps/rest/3.0/search/was/webapp" < file.xml
Note: “file.xml” contains the request POST data.
You’ll notice the operator field value is set to 123, which is the value returned in <lastId> of the previous page output. The GREATER operator is a logical “greater than” (it does not mean greater than or equal to).
Request POST data
<ServiceRequest>
<preferences>
<limitResults>5</limitResults>
</preferences>
<filters>
<Criteria field="name" operator="CONTAINS">Merchant</Criteria>
</filters>
</ServiceRequest>
The number of records is greater than the default pagination value so the <ServiceResponse> element identifies the last ID of the object in the current page output.
XML response
<ServiceResponse ...>
<responseCode>SUCCESS</responseCode>
<COUNT>5</COUNT>
<hasMoreRecords>true</hasMoreRecords>
<lastId>123</lastId>
<data>
<!--here you will find 5 web application records-->
</data>
</ServiceResponse>
To get the next results page, you need to edit your service request in “file.xml” which will be passed to the API request as a POST payload. According to the <lastId> element returned on the first page, you want the next results page to start with the object ID 124 or greater.
API request
curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST"
--data-binary @-"<qualys_base_url>/qps/rest/3.0/search/was/webapp" < file.xml
Note: “file.xml” contains the request POST data.
You’ll notice the operator field value is set to 123, which is the value returned in <lastId> of the previous page output. The GREATER operator is a logical “greater than” (it does not mean greater than or equal to).
Request POST data
<ServiceRequest>
<filters>
<Criteria field="name" operator="CONTAINS">Merchant</Criteria>
<Criteria field="id" operator="GREATER">123</Criteria>
</filters>
</ServiceRequest>
The service request must contain the <preferences> section with the <limitResults> parameter. For the <limitResults> parameter, you can enter a value from 1 to 1,000. You can change which objects are returned and the number of objects by specifying a preferences tag in the POST body of your request.
Request POST data
<ServiceRequest>
<filters>
<Criteria> ... </Criteria>
</filters>
<preferences>
<startFromOffset>100</startFromOffset>
<limitResults>200</limitResults>
</preferences>
</ServiceRequest>