Preface

© 2021 Vector Informatik GmbH - All rights reserved - https://www.vector.com/ - This material may not be reproduced, displayed, modified or distributed without the express prior written permission of the copyright holder. Squore is protected by an Interdeposit Certification registered with Agence pour la Protection des Programmes under the Inter Deposit Digital Number IDDN.FR.001.390035.001.S.P.2013.000.10600.

Foreword

This edition of the API Guide was released by Vector Informatik GmbH.

It is part of the user documentation of the Squore software product edited and distributed by Vector Informatik GmbH.

For information on how to use and configure Squore, the full suite of manuals includes:

User Manual

Target Audience

Squore Installation Checklist

New users before their first installation

Squore Installation and Administration Guide

IT personnel and Squore administrators

Squore Getting Started Guide

End users, new users wanting to discover Squore features

Squore Command Line Interface

Continuous Integration Managers

Squore Configuration Guide

Squore configuration maintainers, Quality Assurance personnel

Squore Eclipse Plugin Guide

Eclipse IDE users

Squore Reference Manual

End Users, Squore configuration maintainers

Squore API Guide

End Users, Continuous Integration Managers

Squore GroovyDoc

End Users, Squore configuration maintainers

Squore Software Analytics Handbook

End Users, Quality Assurance personnel

Licence

No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of the copyright owner, Vector Informatik GmbH. Vector Informatik GmbH reserves the right to revise this publication and to make changes from time to time without obligation to notify authorised users of such changes. Consult Vector Informatik GmbH to determine whether any such changes have been made. The terms and conditions governing the licensing of Vector Informatik GmbH software consist solely of those set forth in the written contracts between Vector Informatik GmbH and its customers. All third-party products are trademarks or registered trademarks of their respective companies.

Warranty

Vector Informatik GmbH makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Vector Informatik GmbH shall not be liable for errors contained herein nor for incidental or consequential damages in connection with the furnishing, performance or use of this material.

This edition of the API Guide applies to Squore 21.1.0 and to all subsequent releases and modifications until otherwise indicated in new editions.

Responsabilities

Approval of this version of the document and any further updates are the responsibility of Vector Informatik GmbH.

Contacting Vector Informatik GmbH Product Support

If the information provided in this manual is erroneous or inaccurate, or if you encounter problems during your installation, contact Vector Informatik GmbH Product Support: https://portal.vector.com/

You will need a valid customer account to submit a support request. You can create an account on the support website if you do not have one already.

For any communication:

  • support@vector.com

  • Vector Informatik GmbH Product Support

    Vector Informatik GmbH - Holder├Ąckerstr. 36 / 70499 Stuttgart - Germany

Getting the Latest Version of this Manual

The version of this manual included in your Squore installation may have been updated. If you would like to check for updated user guides, consult the Vector Informatik GmbH documentation site to consult or download the latest Squore manuals at https://support.squoring.com/documentation/latest. Manuals are constantly updated and published as soon as they are available.

1. Introduction

This document is the API Guide for the Squore REST client API.

The REST client API allows an easy access to the Squore data, through any API client. While we recommend that you read it in its entirety, here are some of the most common section you might be interested to look at:

You can find the list of available API requests, as well as test them, in the Squore interactive Swagger documentation page.

2. URI description

Squore REST API provides access to Squore data using URI paths.

Using these URIs, a REST client application will send HTTP request to Squore server and parse the JSON response from the server. Supported operations are standard HTTP methods GET, PUT, POST and DELETE.

Squore REST API URIs looks like the following:

http://localhost:8180/SQuORE_Server/api/<resource-name>

Where <resource-name> is the name of the entity you want to retrieve, artefacts, projects, findings, etc…​

You can find the list of available entities/resources in the Squore interactive Swagger documentation page.

Squore REST API response is returned to the JSON format.

JSON output response for API request GET /projects
{
	"_links": {
		"self": "http://localhost:8180/SQuORE_Server/api/projects"
	},
	"projects": [ {
			"_links": {
				"self": "http://localhost:8180/SQuORE_Server/api/projects/9"
			},
			"id": 9,
			"name": "Mars",
			"ownerId": 2,
			"versionId": 14,
			"color": -713202,
			"status": "PENDING",
			"group": "C/",
			"creationTime": 1550487011079,
			"artefactId": 4433,
			"rating": "LEVELE",
			"modelUId": "software_analytics"
		}
	]
}

You will find a response example for each request in the Squore interactive Swagger documentation.

3. Access Management

In order to have access to Squore REST API, your Squore license must have the api.export option enabled.

This option is available since Squore version 19.0. If you are not sure wether you have the correct license or not, please contact Squore support at support@vector.com.

Then, Squore users will be able to view and/or use the API depending on their global roles permissions. To know more about global role and API permissions, have a look at Global Roles section.

4. Authentication and Security

Access to Squore data using the API is protected by two types of HTTP authentication schemes:

  • Basic, only for the GET /token API request.

  • Bearer, for all other API requests.

When using a REST client, authentication is done by providing the Authorisation header when making the request.

Example of bearer authentication using cURL
curl -X GET "http://localhost:8180/SQuORE_Server/api/projects" -H "accept: application/json" -H "Authorization: Bearer <token>"

Squore data access via the API is restricted to users permissions in Squore. Users will not be able to access information that they do not have access to in the Squore’s web interface.

Retrieve Permanent Token

First type of tokens that can be generated in Squore are permanent tokens, which are generated from the Squore application’s web interface.

To do so, start by clicking your user name in the menu bar and select the Account Settings option.

CFG api token account menu
Account Settings option

In the Tokens tab enter the name you want to assign to your new permanent token and then click Add.

CFG api token account input
Create new token

Once created, the new token will appear in the table below, alongside the others.

Several tokens can be created and be active at the same time. This can be useful, for example if you want to associate a token with an external script that would use the API to retrieve data.

CFG api token account display
List of available tokens

Permanent tokens have no expiration date. The only way to invalidate them is to revoke them from the Account Settings page, by clicking the Revoke button.

Retrieve Temporary Token

Second type of tokens in Squore are temporary tokens. They are generated by executing the API request: GET /token.

Temporary tokens expire 1 hour after their creation or after 15 minutes of inactivity. They also expire uppon a restart of Squore server.

To know more about what is an API request and how to execute it, have a look at URI description and Using the API sections.

Don’t forget to have a look at Squore interactive Swagger documentation. From there you will be able to:

  • Retrieve and test the list of available API requests, including GET /token.

  • Retrieve cURL examples.

5. Using the API

Any API client supporting REST architecture can be used to make calls to Squore REST API, like cURL, Postman, or else.

Squore 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.

Filters

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

Squore 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/projects?where=(name=Kaptcha) is valid

  • …​/api/projects?where=(branches.name=main) is not valid

{
    "_links": {
        "self": "/projects"
    },
    "projects": [{
            "_links": {
                "self": "/projects/11"
            },
            "id": 11,
            "name": "Kaptcha",
            ...
            "branches": [{
                    "id": 16,
                    "name": "main",
                    "versionId": 46,
                    ...

If comparison value contains special characters (space, parenthesis, etc…​), the value must be surrounded by double quotes : name="my name".

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 artefacts of type FOLDER on project Earth with rating higher than or equal to D
.../api/projects/Earth/artefacts?where=type.id=FOLDER AND rank>=0.125
Filtering file artefacts with extension ".c" on project Earth
.../api/projects/Earth/artefacts?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 parenthesis 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 /artefacts/{artefact-id}/query

  • GET /artefacts/{artefact-id}/highlights/{highlight-id}

It is also not possible to filter on the sub-levels of the _links JSON field.

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

All returned items by Squore API have an attached JSON object named "links".

The links object contains the current link (self) and the information context.

Response example of the API /projects to get the projects list
{
    "_links": {
        "project": "http://localhost:8180/SQuORE_Server/api/projects/9",
        "self": "http://localhost:8180/SQuORE_Server/api/artefacts/4433/findings",
        "model": "http://localhost:8180/SQuORE_Server/api/models/software_analytics",
        "version": "http://localhost:8180/SQuORE_Server/api/versions/14",
        "artefact": "http://localhost:8180/SQuORE_Server/api/versions/14/artefacts/4433"
    },
    "findings": [{
            "_links": {
                "self": "http://localhost:8180/SQuORE_Server/api/findings/4502"
            },
            "id": 4502,
            "tool": "SQUORE",
            "definition": {
                "id": "R_NOASGCOND",
                "name": "Assignment in Boolean",
                "description": "Assignment operators shall not be used in expressions that yield a boolean value"
            },
            "status": "OPEN",
            "locations": [{
                    "id": 2737,
                    "artefact": {
                        "_links": {
                            "self": "http://localhost:8180/SQuORE_Server/api/artefacts/4464"
                        },
                        "id": 4464,
                        "name": "machine_plays_right()",
                        "path": "mars_engine_right.c",
                        "type": {
                            "id": "C_FUNCTION"
                        }
                    },
                    "location": "Line: 438"
                }
            ],
            "readOnly": false,
            "suspicious": false
        },...]
}

Pagination

The pagination feature was implemented to avoid getting too much information at once. This feature is available for all API requests that are susceptible to retrieve many items. To use it, just provide the size and/or page parameter to the query.

cURL example to get projects from the forty-first to the fiftieth
curl -X GET "http://localhost:8180/SQuORE_Server/api/projects?page=5&size=10"
-H "accept: application/json"
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjIsImlhdCI6MTU1MjQwNTgyMzYxMiwiaW50ZXJuYWwiOjAsInNlcSI6M30=.GimdyMOvhjABUHOE4B21bX2zi3q5SEvya257yjMgtWk="

The page and size are optional parameters. If the size parameter was initialized and not the page, the first page is taken by default (&page=1).

The response contains several links that will facilitate the navigation between pages (current/previous/next/first/last).

Response links example to get the projects with pagination
{
  "_links": {
    "previous": "http://localhost:8180/SQuORE_Server/api/projects?page=4&size=10",
    "next": "http://localhost:8180/SQuORE_Server/api/projects?page=6&size=10",
    "first": "http://localhost:8180/SQuORE_Server/api/projects?page=1&size=10",
    "last": "http://localhost:8180/SQuORE_Server/api/projects?page=8&size=10",
    "self": "http://localhost:8180/SQuORE_Server/api/projects?page=5&size=10"
  },
  "projects": [{...}]
}

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:8180/SQuORE_Server/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="

6. Artefact Query JSON Definition

This part describes how to build the JSON body request for API request : POST /artefacts/{artefact-id}/query.

First level Attributes

  • artefactTypes (optional, default: any) JSON array of artefact types to filter on.

  • linkType (optional, default: any) Allows following links to other artefacts. Note that only artefacts with direct links to the current artefact are displayed.

  • linkDirection (optional, default: OUT) is one of IN or OUT and allows to specify the direction of the links to follow.

  • columns (mandatory) JSON array of column object.

  • orders (optional) JSON array of order object.

  • filters (optional) JSON array of filter object.

  • resultSize (optional, default: all) is the number of returning items.

  • hidePath (optional, default: false) is the flag to hide the path.

  • hideRating (optional, default: false) is the flag to hide the rating.

Columns Attributes

The column object is used to add a column to the list of artefacts returned.

  • type (mandatory) define the type of the column. The possible values are MEASURE, INDICATOR or INFO.

  • id (mandatory) is the ID of the measure, indicator or textual information to display.

  • displayType (optional, only for indicator type, default: NAME) is the label to display in the header. The supported values are:

    • RANK for the indicator’s rank

    • ICON for the indicator’s rank icon

    • NAME for the indicator level’s name

    • MNEMONIC for the indicator level’s mnemonic

  • useBackgroundColor(optional, default: false) allows you to use the indicator level as the background colour of the cell. This is only valid when using a column with indicatorId. You can also control the transparency of the background colour with the attribute. Only for indicator type.

  • alpha (optional, default: 100) alpha which accepts a value between 0 (transparent) and 255 (opaque). Only when useBackgroundColor is used.

  • excludingTypes (optional, default: none) lists the artefact types for which the metric should not be displayed. This allows refining the types entered in the main filter above.

Orders Attributes

The order object is used to specify sorting directives.

  • type (mandatory) define the measure type. The possible values are ROOT_MEASURE or MEASURE.

  • id (mandatory) is the ID of the measure

  • order (mandatory) is the sort order for measure. Supported values are:

    • ASC for ascending

    • DESC for descending

  • orderType (mandatory) define the sorted value for the measure. Supported values are:

    • VALUE is the value of the measure

    • RANK is the rank of the measure

    • DIFF_VALUE is the difference between values

    • DIFF_RANK is the difference between ranks

Filters Attributes

The filter object is used to specify extra filtering conditions for the artefacts to return.

  • type (mandatory) define the type of the column. The possible values are measure, indicator or info.

  • id (mandatory) is the ID of the measure, indicator or textual information to return.

  • data (mandatory) JSON Object that contains fields :

    • checked (optional,default: ?) is the values of the measure/indicator/info you want to return. (or not if invert is equals to True)

    • bounds (optional,only for indicators and measures types, default: [;[) is the value limits. Infinite bounds can be specified by omitting the number, e.g.: [0;[ or [0;] for any null or positive number.

    • patterns (optional,only for info types, default: *) is the value patterns of the data you want to return. The available patterns are:

      • * Matches any sequence of characters in string, including a null string.

      • ? Matches any single character in string.

  • invert (optional, default: false) allows to invert the condition.

For the filter info type, you can’t use the fields 'patterns' and 'checked' together. The checked field has priority.

Query definition example

{
	"artefactTypes": ["MODULES"],
	"linkType": "IMPLEMENTATION",
	"linkDirection": "IN",
	"hideRating": true,
	"columns": [{
			"type": "INDICATOR",
			"id": "CPXT",
			"displayType": "ICON",
			"useBackgroundColor": false
		}, {
			"type": "MEASURE",
			"id": "VG"
		}, {
			"type": "MEASURE",
			"id": "NEST"
		}, {
			"type": "MEASURE",
			"id": "NPAT"
		}, {
			"type": "MEASURE",
			"id": "STAT"
		}, {
			"type": "MEASURE",
			"id": "NOP"
		}, {
			"type": "MEASURE",
			"id": "DOPD"
		}, {
			"type": "MEASURE",
			"id": "VOCF"
		}
	],
	"orders": [{
			"type": "MEASURE",
			"id": "CPXT",
			"order": "DESC",
			"orderType": "VALUE"
		}, {
			"type": "MEASURE",
			"id": "VG",
			"order": "ASC",
			"orderType": "VALUE"
		}
	],
	"filters": [{
			"type": "measure",
			"id": "CPXT",
			"data": {
				"bounds": ["[0.0;["]
			}
		}
	]
}

Index