Using the API

Any API client supporting REST architecture can be used to make calls to PC-lint Plus View REST API, like cURL, Postman, or else.

PC-lint Plus View REST API offers several features that can help you better understand and/or customize the API responses, you will find their descriptions in the following sections.

Version

In order to provide better flexibility and allow for backward compatibility, the PC-lint Plus View REST API is versioned. Current version for the REST API is: v3.

The version is set up in the API request header with the accept parameter, as follows:

  • accept: application/vnd.squore.app-<version>+json.

Note that you can also use the value, latest, if you want your API request to always use the latest available version of the API known to PC-lint Plus View server.

Example of version latest specified in header using cURL
curl -X GET "http://localhost:8280/api/projects" -H "accept: application/vnd.squore.app-latest+json" -H "Authorization: Bearer <token>"
Example of version v3 specified in header using cURL
curl -X GET "http://localhost:8280/api/projects" -H "accept: application/vnd.squore.app-v3+json" -H "Authorization: Bearer <token>"

If no version is specified in the header, then the default version specified in Administration > System page is used (Configuring API Default Version). If multiple headers are defined, then the most recent API version is used.

Filters

Filters can be used to reduce/customize the API requests responses.

PC-lint Plus View REST API offers two filtering methods:

  • Filtering the data to reduce the API requests scope and improve performances

  • Filtering the JSON response fields to improve the response readability and/or processing

Filtering Data

Filtering the data will help you reduce the API requests scope and improve performances.

To filter the data, the keyword where must be added at the end of the URI, followed by the filtering expression. The syntax is inspired by SQL/JQL but with some particularities because it is used in a URI.

Understanding the filtering syntax:

…​/api/projects?where=(analysisTime!=2020-12-25 OR analysisTime!=2020-12-24)

Where:

  • ?where= is the keyword for introducing the filtering query.

  • (…​) are the parenthesis used to group conditions.

  • analysisTime is the JSON field we want to compare to.

  • != is the comparison operator.

  • 2020-12-25 is the comparison value.

  • OR is a logical operator, make sure to add spaces before and after the operator.

Supported JSON fields are the ones from the JSON responses and supported data types are, strings, booleans, integers and dates (with format yyyy-MM-dd, without the time).

Sub-levels arrays cannot be filtered. In the example below :

  • …​/api/artifacts/{artifact-id}/findings?where=(tool=CPPCHECK) is valid

  • …​/api/artifacts/{artifact-id}/findings?where=(locations.artifact.name="machine_read_file()") is not valid

[
  {
    "id": 126,
    "description": "Common realloc mistake: 'name' nulled but not freed upon failure",
    "tool": "CPPCHECK",
    "relaxStatus": {
      "id": "OPEN_DEFAULT"
    },
    "locations": [
      {
        "location": "56",
        "artifact": {
          "id": 4,
          "name": "machine_read_file()",
          "path": "apps/machine.c",
          "type": {
            "id": "C_FUNCTION",
            "name": "C Function"
          }
        }
      }
    ],
    "count": 1,
    "ruleId": "MEMLEAKONREALLOC",
    "readOnly": false,
    "new": false,
    "manual": false,
    "suspicious": false
  },
  ...
]

If comparison value contains special characters (space, parenthesis, etc…​), the value must be surrounded by double quotes. And in case the special characters are double quotes, they need to be escaped by being doubled, as follows:

  • …​/api/projects?where=(name="my name").

  • …​/api/projects?where=(name="my name ""with double"" quotes").

Logical Operators

  • OR returns true if at least one operand evaluates to true.

  • AND returns true if both operands evaluates to true.

  • IN returns true if the field value is in the provided list of values.

  • NOT IN returns true if the field value is not in the provided list of values.

  • IS NULL returns true if the field value equals NULL.

  • IS NOT NULL returns true if the field value does not equal NULL.

Logical operators need to be surrounded by spaces, one before and one after.

Comparators

  • Equals, = : returns true if both operands are equals.

  • Not equals, != : returns true if both operands are not equals.

  • Greater than, > : returns true if left operand is greater than right operand.

  • Greater than or equal, >=: returns true if left operand is greater than or equal to right operand.

  • Less than, < : returns true if left operand is less than right operand.

  • Less than or equal, <= : returns true if left operand is less than or equal to right operand.

  • Contains, ~ : returns true if the left operand contains the string specified as right operand.

  • Starts with, ~test* : returns true if the left operand starts with the specified string, test, followed by anything.

  • Ends with, ~*test : returns true if the left operand ends with the specified string, test, preceded by anything.

Examples

Filtering projects with global rating lower than B amongst Earth, Mars, Venus and Pluto
.../api/projects?where=(name IN (Earth,Mars,Venus) OR name=Pluto) AND level.id NOT IN (LEVELA,LEVELB)
Filtering artifacts of type FOLDER on project Earth with rating higher than or equal to D
.../api/projects/Earth/artifacts?where=type.id=FOLDER AND rank>=0.125
Filtering file artifacts with extension ".c" on project Earth
.../api/projects/Earth/artifacts?where=name~*.c

Depending on the REST client you are using, you might have to encode the URI as follows:

.../api/projects?where=type.id%3DFOLDER%20AND%20rank%3E%3D0.125

Filtering Fields

Filtering fields will help you improve the JSON response parsing/processing and readability.

To filter fields, the keyword fields must be added at the end of the URI, followed by the filtering expression.

Understanding the filtering syntax:

…​/api/projects?fields=name,level.id,status(id,name)

Where:

  • ?fields= is the keyword for introducing the filtering query.

  • name, level, status are the first level JSON fields.

  • id, (id,name) are sub-levels JSON fields.

Wanted fields are separated by a coma, name,level, and sub-levels fields are accessed by a point, level.id.

If multiple sub-levels fields are expected, then the point is replaced by the list of sub-levels fields enclosed in parentheses and separated by a coma, status(id,name).

Filtering fields is not available for the following API requests, since they have their own filtering system :

  • GET /dump

  • GET /artifacts/{artifact-id}/query

  • GET /artifacts/{artifact-id}/highlights/{highlight-id}

Examples

Filtering JSON fields for findings
.../api/artifacts/439/findings?fields=definition.categories.level.id,definition.families
Filtering JSON nested fields for findings
.../api/artifacts/439/findings?fields=definition(families,categories(level(id,name),scale.name))

Localization

The localization feature allows to choose which language must be used for the API responses content.

By default, the language of the user who created the token is used. It is possible to force the language by passing the information in the header.

It is also possible to change the timezone, by default it is the user’s timezone.

cURL example in German and Europe/Germany timezone
curl -X GET "http://localhost:8280/api/projects"
-H "accept-language: en"
-H "timezone: Europe/Germany"
-H "accept: application/json"
-H "Content-Type: application/json"
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjIsImlhdCI6MTU1MjQ2NTg0MzE2NiwiaW50ZXJuYWwiOjAsInNlcSI6N30=.EBMsApnJ7BdIM6QYi225azgZVwb2bE7_J8TcTIEZEDQ="