PATCH MANAGEMENT FOR EDUCATIONAL INSTITUTIONS

Thursday | 12 PM EDT / 6 PM CEST

REGISTER FOR THE WEBINAR
Homepage 5 API Documentation 5 Filtering Data

Filtering Data

 

For many GET calls, Action1 API enables you to narrow down data in the returned results. For example, you can filter out critical updates or retrieve only those endpoints that are currently disconnected. 

Understanding query parameters

Filtering is implemented with a help of query paramaters. Unlike path parameters that are mandatory, query parameters are optional and you can use them only if you want to filter returned results.

An API call can include several query parameters that can modify it and affect what data the call returns. Query parameters are appended to the path and separated from the call URL with ? sign. In case you want to use multiple parameters, separate them with & sign. Make sure to provide a value for each query parameter you specify in the path. 

For example, https://app.action1.com/api/3.0/updates/{organization_id}?security_severity=important&approval_status=new query will return information about new (unapproved) important updates in your organization.

Query parameters are unique to API calls. To learn about parameters and their values that you can use to filter data for a specific API call, see API specification.

Trying it out

Try sending requests to the same endpoint with and without query paramters to see how Action1 filters returned data. For example:

GET /updates/all – no filtering

Request:

curl -XGET -H "Authorization: Bearer JWT-TOKEN" https://app.action1.com/api/3.0/updates/all

Response:

In the response includes all available updates. The approval status, severity, release date aren’t taken into account.

Note: The example below is truncated, the API call returns more detailed data.

{
   "id": "1",
   "type": "ResultPage",
   "name": "",
   "self": "https://app.action1.com/api/3.0/updates?from=0&limit=50",
   "items": [
      {
          "id":  "89e11227-761b-4396-bf37-37a2b641fa84_builtin",
          "type": "Package", 
          "builtin": "yes",
          "name": "2021-01 Update for Windows Server 2019 for x64-based Systems (KB4589208)",
          ...
          "versions": [
             {
                 "id": "89e11227-761b-4396-bf37-37a2b641fa84_builtin",
                 "type": "Version",
                 "version": "Latest",
                 "security_severity": "None",
                 "approval_status": "Approved",
                 ...
             }
          ]
       }
       {
          "id": "Google_Google_Chrome_1570243626751_builtin",
          "type": "Package", 
          "builtin": "yes", 
          "name": "Google Chrome"  
          ...
          "versions": [ 
              { 
 
                "id": "103.0.5060.134_1658342379835",  
                "type": "103.0.5060.134",  
                "version": "Latest",  
                "security_severity": "Important",  
                "approval_status": "New",  
                ...  
             }  
          ]
       }
       {
          "id": "Adobe_Adobe_Acrobat_Reader_DC_1570155380192_builtin",
          "type": "Package", 
          "builtin": "yes", 
          "name": "Adobe Acrobat Reader DC"  
          ...
          "versions": [ 
              { 
 
                "id": "21.007.20099_1634152671802",  
                "type": "Version",  
                "version": "21.007.20099",  
                "security_severity": "None",  
                "approval_status": "Declined",  
                ...  
             }  
          ]
       }      
      {...}
      {...}
    ]
    "total_items": "50",
    "limit": "50",
    "next_page": "",
    "prev_page": ""
}

Compare with Action1 webconsole:

Updates without filtering - Compare your API query to webconsole results

GET /updates/all - with filtering: locate records with Important severity and New status

Request:

curl -XGET -H "Authorization: Bearer JWT-TOKEN" https://app.action1.com/api/3.0/updates/all?security_severity=Important&approval_status=New

Response:

The call returns records that match both filtering criterias specified in the path.

Note: The example below is truncated, the API call returns more detailed data.

{
   "id": "1",
   "type": "ResultPage",
   "name": "",
   "self": "https://app.action1.com/api/3.0/updates?from=0&limit=50&security_severity=Important&approval_status=New",
   "items": [     
       {
          "id": "Google_Google_Chrome_1570243626751_builtin",
          "type": "Package", 
          "builtin": "yes", 
          "name": "Google Chrome"  
          ...
          "versions": [ 
              { 
 
                "id": "103.0.5060.134_1658342379835",  
                "type": "103.0.5060.134",  
                "version": "Latest",  
                "security_severity": "Important",  
                "approval_status": "New",  
                ...  
              }  
          ]
       }  
    ]
    "total_items": "50",
    "limit": "50",
    "next_page": "",
    "prev_page": ""
}

Compare with Action1 webconsole:

With filtering