7.2.1.8. Project API

Endpoints

GET	/projects/{projectName}	DEPRECATED Use /api/projects/{projectName} instead
GET	/api/projects/{projectName}	Get Project Info
DELETE	/api/projects/{projectName}	Delete a project and all its artifact files
GET	/api/projects/{projectName}/analyzed_files	Get Analyzed Files
GET	/api/projects/{projectName}/queryVersion	Query a Version
POST	/api/projects/{projectName}/update_sourcecode_repositories	Update VCS-Repositories
GET	/projects/{projectName}/rules	DEPRECATED Use /api/projects/{projectName}/rules instead
GET	/api/projects/{projectName}/rules	Get flat list of rules configured for the project
POST	/api/projects/{projectName}/create_branch_project	Create a branch project from an existing, managed project
GET	/api/projects/{projectName}/export_backup	Download a backup of the given project as a single file
POST	/api/create_project_from_backup	Upload a previously downloaded backup file to create a new project
GET	/api/projects/{projectName}/ir	Download the projects IR file if available
GET	/api/projects/{projectName}/rfg	Download the projects RFG file if available

GET /projects/{projectName}

Use /api/projects/{projectName} instead.

Deprecated since 7.2.0.

Parameters:

• projectName – path

  The project name

Status Codes:

• 200 OK –

  Body Type: ProjectInfo

  Successful response

GET /api/projects/{projectName}

Get Project Info.

Since: 7.2.0

Provides meta information about the specified project.

In the Python API this functionality is provided by axivion.dashboard.Project.info().

Parameters:

• projectName – path

  The project name

Status Codes:

• 200 OK –

  Body Type: ProjectInfo

  Successful response

DELETE /api/projects/{projectName}

Delete a project and all its artifact files.

Since: 7.7.3

Deletes the project as well as all its artifact files.

WARNING:

If you delete a project this way, there is no way of restoring it unless you have created a backup before via /api/projects/{projectName}/export_backup.

This operation is only allowed for managed projects, i.e., projects that were created or migrated via the managed_upload mode of axivion_ci or branched from such a project.

Parameters:

• projectName – path

  The project name

Status Codes:

• 403 Forbidden –

  Body Type: Error

  In case there is insufficient permission to delete a project with the given name, regardless of whether the project actually exists.

• 404 Not Found –

  Body Type: Error

  In case the project does not exist.

• 204 No Content – The project was deleted successfully.

GET /api/projects/{projectName}/analyzed_files

Get Analyzed Files.

Returns the list of analyzed files.

Parameters:

• projectName – path

  The project name

• version – query

  The optional analysis version specified as version query string.

  Defaults to latest.

Status Codes:

• 200 OK –

  Body Type: AnalyzedFileList

  The files analyzed in the given version.

GET /api/projects/{projectName}/queryVersion

Query a Version.

Since: 6.9.8

Resolves a version query string on a project.

Returns the exact matching version or the first version before the specified version expression.

In the Python API this functionality is provided by axivion.dashboard.Project.query_version().

Parameters:

• projectName – path

  The project name

• q – query

  a version query string

Status Codes:

• 200 OK –

  Body Type: AnalysisVersion

  Successful response

POST /api/projects/{projectName}/update_sourcecode_repositories

Update VCS-Repositories.

Since: 6.9.15

Updates associated VCS-Repositories.

This may be needed for distributed VCS like git when the update-command triggered by the CI for some reason is unsuccessful. In the Python API this functionality is provided by axivion.dashboard.Project.update_sourcecode_repositories().

Parameters:

• projectName – path

  The project name

Status Codes:

• 200 OK –

  Body Type: RepositoryUpdateResponse

  Successful response. Also in case of VCS errors.

GET /projects/{projectName}/rules

Use /api/projects/{projectName}/rules instead.

Since: 6.5.0

Deprecated since 7.2.0

Parameters:

• projectName – path

  The project name

Status Codes:

• 200 OK –

  Body Type: RuleList

  Successful response

GET /api/projects/{projectName}/rules

Get flat list of rules configured for the project.

Since: 7.2.0

Parameters:

• projectName – path

  The project name

• version – query

  The optional analysis version specified as version query string.

  Defaults to latest.

Status Codes:

• 200 OK –

  Body Type: RuleList

  Successful response

POST /api/projects/{projectName}/create_branch_project

Create a branch project from an existing, managed project.

Since: 7.7.3

Creates a new project from an existing one.

No permissions for the newly created project will be assigned automatically, so you will usually want to have assigned project-specific permissions using wildcard patterns.

This operation is only allowed for managed projects, i.e., projects that were created or migrated via the managed_upload mode of axivion_ci or branched from such a project.

This operation becomes a NOOP if a projects with given name already exists and if the origin of this project is {projectName} with matching sourceVersion. The version check can be disabled by leaving out sourceVersion in the request body.

Request Body:

• Body Type: ProjectBranchRequest

Parameters:

• projectName – path

  The project name

Status Codes:

• 403 Forbidden –

  Body Type: Error

  If there are insufficient permissions to perform the request, regardless of whether source or target project exist.

• 404 Not Found –

  Body Type: Error

  In case the source project does not exist.

• 200 OK –

  Body Type: ProjectReference

  The newly created project

GET /api/projects/{projectName}/export_backup

Download a backup of the given project as a single file.

Since: 7.7.3

Downloads the project artifacts as a single file.

The downloaded file is of the same format that is also expected for restoring a project from a backup.

You may find it easy to modify the contents of such a file or create one from scratch, but be aware, that its format is NOT part of the API and may change any time.

This operation is only allowed for managed projects, i.e. projects that were created or migrated via the managed_upload mode of axivion_ci or branched from such a project.

Parameters:

• projectName – path

  The project name

Status Codes:

• 403 Forbidden –

  Body Type: Error

  If there are insufficient permissions to perform the request, regardless of whether the project exists.

• 404 Not Found –

  Body Type: Error

  In case the given project does not exist.

• 200 OK –

  Body Type: binary data

  The backup file contents

POST /api/create_project_from_backup

Upload a previously downloaded backup file to create a new project.

Since: 7.7.3

The uploaded file is expected to be of the same format as is provided by /api/projects/{projectName}/export_backup.

This operation will create a managed project, i.e. adding further analysis-results to this project will require a configuration with the upload setting enabled.

Request Body:

• Body Type: binary data

Parameters:

• name – query

  name of the project to create

Status Codes:

• 403 Forbidden –

  Body Type: Error

  If there are insufficient permissions to perform the request, regardless of whether the target project exists.

• 400 Bad Request –

  Body Type: Error

  If a project with that name already exists.

• 200 OK –

  Body Type: ProjectReference

  The newly created project

GET /api/projects/{projectName}/ir

Download the projects IR file if available.

Since: 7.12.0

Status Codes:

• 200 OK –

  Body Type: binary data

  Successful response

• 404 Not Found – The project does not have an IR file

GET /api/projects/{projectName}/rfg

Download the projects RFG file if available.

Since: 7.12.0

Status Codes:

• 200 OK –

  Body Type: binary data

  Successful response

• 404 Not Found – The project does not have an RFG file

Types

AnalyzedFileList	Contains a list of analyzed file descriptions
AnalyzedFile	Describes an analyzed file in a version
ProjectInfo	Information about a project
UserRefType (enum)	User Type
UserRef	Information about a user
ToolsVersion	Refers to a specific version of the Axivion Suite
AnalysisVersion	Describes the version of analysis data of a certain Project
VersionKindCount	Kind-specific issue count statistics that are cheaply available
VersionKindCounts	Holds VersionKindCount objects for the different issue kinds
IssueKindInfo	Describes an Issue Kind
RepositoryUpdateMessage	A log message with an associated log level
MessageSeverity (enum)	The log-level of a message
RepositoryUpdateResponse	Response to Repository Update Request
RuleList	Contains a list of rules
Rule	A rule configured on a project
ProjectBranchRequest	Request Data for creating a branched Project

AnalyzedFileList

Contains a list of analyzed file descriptions.

Properties:

• version (AnalysisVersion) The version this list was queried with.

• rows (array) Element Type: AnalyzedFile.

AnalyzedFile

Describes an analyzed file in a version.

Properties:

• path (string) The absolute path of the file.

• isSystemHeader (boolean) Indicates whether this file is a system header file.

• languageName (string) The name of the language used to analyze this file.

ProjectInfo

Information about a project.

Properties:

• name (string) The name of the project. Use this string to refer to the project.

• issueFilterHelp (string) Since 6.5.0. A host-relative URL that can be used to display filter-help meant for humans.

• tableMetaUri (string) Since 6.9.0. URL to query the table meta data (column definitions). Needs the issue kind as a query parameter kind.

• users (array) Element Type: UserRef. List of users associated with the project and visible to the authenticated user.

• versions (array) Element Type: AnalysisVersion. List of analysis versions associated with the project.

• issueKinds (array) Element Type: IssueKindInfo. List of IssueKinds associated with the project.

• hasHiddenIssues (boolean) Whether or not the project has hidden issues. When this is false then UI should try to hide all the complexity related with hidden issues.

UserRefType

User Type.

Since: 7.1.0

• VIRTUAL_USER - virtual user that does not represent a specific person

• DASHBOARD_USER - a regular, explicitly managed user

• UNMAPPED_USER - a user that is not explicitly managed and e.g. only known via an analysis result

UserRef

Information about a user.

Properties:

• name (string) User name. Use this to refer to the same user.

• displayName (string) Use this for display of the user in a UI.

• type (string) Possible values: UserRefType. Since 7.1.0. User Type

• isPublic (boolean) Since 7.1.0. Whether this user is a so-called public user.

ToolsVersion

Refers to a specific version of the Axivion Suite.

Properties:

• name (string) Version number for display purposes

• number (string) Parseable, numeric version number suitable for version comparisons

• buildDate (string) Build date in an ISO8601-parseable string of the form YYYY-MM-DD

AnalysisVersion

Describes the version of analysis data of a certain Project.

Properties:

• date (string) The ID used to refer to an AnalysisVersion in this API.

  ISO8601 compatible date-strings that are guaranteed to contain time zone information.

  An example version string is 2020-11-23T09:37:04.797286Z.

  The precision of these dates is undefined, thus in order to be sure to refer to exactly the same version when specifying a version as an argument e.g. when querying issues, you must use this exact string.

  If you want to interpret the version-date e.g. for passing it to a graph-drawing library or to order a list of AnalysisVersion`s, it is easier to use the field `millis instead of parsing these dates.

• label (string) Since 7.6.0. Optional label of the version.

• index (integer) The 0-based index of all the known analysis versions of a project.

  The version with index 0 never contains actual analysis data but always refers to a fictional version without any issues that happened before version 1.

• name (string) The display name of the analysis version consisting of the date formatted with the preferred time zone of the user making the request and the label in parentheses.

• millis (integer) Analysis version timestamp in milliseconds

  The number of milliseconds passed since 1970-01-01T00:00:00 UTC

  Meant for programmatic interpretation of the actual instant in time that represents a version.

• issueCounts (VersionKindCounts) Since 6.6.0. For every Issue Kind contains some Issue counts.

  Namely the Total count, as well as the newly Added and newly Removed issues in comparison with the version before.

  N.B. The Bauhaus Version used to analyze the project must be at least 6.5.0 in order for these values to be available.

• toolsVersion (ToolsVersion) Since 6.9.15. Version information of the Axivion Suite used to do this analysis run.

  Note, that this field is only available when the analysis was done with at least version 6.5.0.

• linesOfCode (integer) Since 7.0.4. DEPRECATED. The total lines of code of the project at the current version if available. This property will be removed in a future version. Use queryMetricValueRange instead.

• cloneRatio (number) Since 7.0.4. DEPRECATED. The clone ratio of the project at the current version if available. This property will be removed in a future version. Use queryMetricValueRange instead.

VersionKindCount

Kind-specific issue count statistics that are cheaply available.

Properties:

• Total (integer) The number of issues of a kind in a version.

• Added (integer) The number of issues of a kind present in a version that were not present in the previous version.

• Removed (integer) The number of issues of a kind that were present in the previous version and are not present in the current version any more.

VersionKindCounts

Holds VersionKindCount objects for the different issue kinds.

Properties:

• AV (VersionKindCount)

• CL (VersionKindCount)

• CY (VersionKindCount)

• DE (VersionKindCount)

• MV (VersionKindCount)

• SV (VersionKindCount)

IssueKindInfo

Describes an Issue Kind.

Properties:

• prefix (string) Possible values: IssueKind. one of AV, CL, CY, DE, MV, SV

• niceSingularName (string) A singular string for using in UI texts about the issue kind.

• nicePluralName (string) A plural string for using in UI texts about the issue kind.

RepositoryUpdateMessage

A log message with an associated log level.

Contains messages returned from the VCS-adapters reporting on the VCS update result.

Properties:

• severity (string) Possible values: MessageSeverity. The log-level of the message.

• message (string) the log-message. It may contain new-lines.

MessageSeverity

The log-level of a message.

• DEBUG

• INFO

• WARNING

• ERROR

• FATAL

RepositoryUpdateResponse

Response to Repository Update Request.

Contains messages returned from the VCS-adapters reporting on the VCS update result.

Properties:

• messages (array) Element Type: RepositoryUpdateMessage. The messages returned from the VCS-adapters

• hasErrors (boolean) Whether at least one of the messages is at least an ERROR

• hasWarnings (boolean) Whether at least one of the messages is at least a WARNING

RuleList

Contains a list of rules.

Since: 6.5.0

Properties:

• rules (array) Element Type: Rule.

Rule

A rule configured on a project.

Since: 6.5.0

Properties:

• name (string) the rule name (possibly renamed via configuration)

• original_name (string) the original (unrenamed) rule name

• disabled (boolean) Whether or not the rule was disabled.

  Note, that this value is only available for analysis runs done with at least 6.5.0

ProjectBranchRequest

Request Data for creating a branched Project.

Since: 7.7.3

Parameters for branching an existing Dashboard Project.

Properties:

• sourceVersion (string) The analysis version date of the source database specified as version query string. With Dashboard version 7.8.3, this property became optional, where, if omitted, it defaults to latest. Moreover, leaving this property out disables the version check for already existing branches, i.e., if a project with given name already exists, only the origin check is applied; the version check is skipped.

• targetProject (string) Name of a non-existing project that will be the name of the branched project. The created project will be managed, i.e., its artifacts will reside inside the artifacts-folder and analysis the analysis of the branched project is supposed to happen with the upload-feature of axivion_ci.