Recently, I spent far too much time looking for what should have been obvious. Over the years I have filled the roll of a specialized-generalist, a jack-of-all-trades-master-of-none developer and technical architect. In simple terms, I connect information from different systems and processes to solve or measure business issues, then move on.
I especially rely on vendor documentation to understand quickly how to retrieve useful data out of troves of noise. I try filter to only what is needed and to do so efficiently.
RESTful APIs follow standard on connectivity and format when querying for information. How that information is filtered, searched, and selected is determined by the underlying system the API exposes. Some vendor APIs allow a great deal of specificity on returned attributes and search criteria. Other systems are less nuanced. In all cases, knowing how to ask the question is key.
Defining operators, the conjunctions that join search phrases and clauses, are important. If you want to know if Y is between X and Z, depending on the underlying products the questions can be expressed in several ways. Having to guess which operators to use is annoying and time consuming. To illustrate how playing a guessing game is a challenge, here are a few pseudo-examples of methods I have seen and used to determine if a value is in a range.
Is Y between X and Z:
Y BETWEEN(X ,Z) = 1
Y > X AND Y < Z
Y > X & Y < Z
Compare(Y, X) > -1 and Compare(Y, X) < 1
InRange(Y, X, Z) = 0
"filters": {"field": myAttribute, "operator": between, "item": Y, "value": Z, "value": Z}
For anyone looking for the defined operators for Rapid7’s InsightVM platform API, here is the example I found in the product forum. As access may require an account, the salient parts are included below from John Hartman’s posted solution.
https://discuss.rapid7.com/t/insightvm-cloud-api-v4-multiple-parameters-in-search-query/14177
So the cloud integration API as far as POSTing an asset search is concerned can use the criteria directly from the Query Builder. If you build your query there first then you can get the correct field names and see the syntax used.
{
"asset": "asset.name CONTAINS 'abc123.com' && last_scan_end > 2019-09-04T23:16:57.903Z",
"vulnerability": "severity IN ['Critical', 'Severe']"
}&& = AND
|| = OR
It is the double-ampersand for the “and” operator I was looking for! So simple in the end.
My only wish is that API documentation include a more complete list of examples, syntax, and query-able definitions. While a product forum is helpful for working through the odd complexities, it is less suited for the, “Here are basic API rules you will need to be functional. Good luck!” Nevertheless, I am happy I found the tiny tidbit I was looking for so I could get back to work. I appreciate the tip on using the UI query builder. If you find this post, I suspect you are feeling much the same as I did.
Time to mine the salt from the sand, not from my sweat.