Übersetzungen exportieren

Einstellungen

Gruppe

Sprache

Format

Für die Offline-Übersetzung exportieren

Im systemeigenen Format exportieren

Im CSV-Format exportieren

{{DISPLAYTITLE:Data import/export interface}}The data import/export interface of HITGuard is a REST API that complies with the OpenAPI 3.0 specification. It is therefore an API that can be used by applications.

This page describes how to enable the REST API, how to get permission to use the REST API (ApiKeys) and where to find the REST API documentation (SwaggerUI).

Successfully performed imports also generate an import log in the menu item Data import ([[Special:MyLanguage/Datenimport|"Administration → Data import | Import logs]])!

[[Datei:REST API Importprotokoll.png|thumb|left|900px]]

== Configuration ==

To enable the REST API, the following property must be set in the configuration file "appsettings.json":

* <code>"RestApi": { "Enabled": true } </code>

If this property does not exist or it is set to "false", the REST API is completely disabled and Administrators will no longer see the ApiKey section under their profile nor the REST API settings under Global Settings.

== Settings ==

If the REST API has been enabled in "appsettings.json", Administrators will find a new area in the Global Settings, where the REST API can be enabled and disabled at any time.

[[Datei:REST API Einstellungen.png|thumb|left|902px]]

* Activate REST API:
:: This option enables the endpoints of the REST API. If this option is disabled, the REST API does not accept any requests.

* Activate SwaggerUI:
:: This option enables the SwaggerUI, which is an interactive documentation of the REST API. It can be accessed at "/swagger". 
::This option has no effect on the functionality of the REST API. If it is disabled, the REST API will still work if it is enabled.
:: This page is only relevant for developers who want to communicate with the REST API. 
:: If the documentation is no longer needed, the SwaggerUI page should be disabled.

== Swagger/OpenAPI documentation ==

As described before, the documentation of the REST API can be found under "/swagger" when the SwaggerUI is enabled.

On this page, developers will find all the information they need to communicate with the REST API.

On this page, you also find the JSON description of the REST API. This description can be used by tools (e.g. [https://editor.swagger.io/| editor.swagger.io]) to automatically generate clients for the REST API.

'''Important''': ID parameters mentioned in the documentation do not refer to HITGuard internal IDs in the context of the REST API. They refer to the HITGuard field "External ID".

[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]]

{| class="wikitable"
! colspan="2" | Overview
|-
!Structural analysis edges
|PUT /api/v2/asset-edges → Adds relationships in the structural analysis between resources, organizational units, processes, and data categories. DELETE /api/v2/asset-edges → Deletes manually set relationships between resources and resources, organizational units, processes, and data categories.
|-
!Tickets
|PUT /api/tickets → Creates a new ticket in a management system or updates it. DELETE/api/tickets/{id} → Deletes a ticket by its external ID.
|-
!Management systems
|GET /api/management-systems → Produces a list of the available management systems. This list contains the management system IDs.
|-
!Users
|DELETE /api/users/deactivate/{userName} → Deactivates or deactivates and anonymizes a user by the username. PUT /api/v2/users → Creates or updates one or multiple users. Caution: updating users only works if the AD integration is deactivated.
|-
!Data categories
|PUT /api/data-categories → Creates new data categories or updates them. GET/api/data-categories → Produces a list of the available data categories. GET/api/data-categories/data-classes → Produces a list of the available data classes. DELETE/api/data-categories/{id} → Deletes a data category by the external key.
|-
!Measures
|PUT /api/v2/measures → Creates a new measure or updates it. PUT/api/measures/close/{id} → Puts a measure into the state "Completed" by the ID. PUT/api/measures/close/byKey/{id} → Puts a measure into the state "Completed" by the external ID. DELETE/api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET/api/measures/{state} → Produces a list of all measures in a specific state.
|-
!Organizational units
|PUT /api/org-units → Creates an organizational unit or updates it. GET/api/org-units → Produces a list of organizational units. DELETE/api/org-units/{id} → Deletes an organizational unit by the ID.
|-
!Processes
|PUT /api/processes → Creates a process or updates it. GET/api/processes → Produces a list of processes. DELETE/api/processes/{id} → Deletes a process by the ID.
|-
!Resources
|PUT /api/resources → Creates a resource or updates it. GET/api/v2/resources → Produces a list of resources. GET/api/v2/resources/{id} → Retrieves the information of a specific resource by the ID. DELETE/api/resources/{id} → Deletes a resource by the ID.
|-
!Risks
|PUT /api/v2/risks → Creates a risk in a management system or updates it. POST /api/v2/risks/submit → Creates a new Risk in state "Submitted" in the provided managementsystem. GET/api/v2/risks/ → Produces a list of all available risks. GET/api/v2/risks/{id} → Retrieves the information of a specific risk by the ID. DELETE/api/v2/risks/{id} → Deletes a risk by the ID.
|-
!Suppliers
|PUT /api/suppliers → Creates or updates a supplier.
|-
|}

== Versionierung ==
Aktuell gibt es 2 Versionen der API: "v1" und "v2". In Swagger kann zwischen den Versionen hin und her gewechselt werden.
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zur Zeit sind die Endpunkte auf diese beiden Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.

Endpoints marked as deprecated in "v1" should no longer be used and will be removed in the future. Use the endpoints in "v2" instead.

=== Change log ===

==== Changes from "v1" to "v2" ====

* Measures
** PUT /api/v2/measures replaces PUT /api/measures
*** Configurations regarding the necessity test can no longer be set or changed, as those use internal IDs
*** The parameter "ID" now refers to the HITGuard field "External ID" and no longer the internal ID
** PUT /api/measures/close/{id}
*** was marked as deprecated as it used an internal ID → only use PUT /api/measures/close/byKey going forward!
** General
*** The parameter "state" now uses enumeration values
* Asset edges
** PUT /api/v2/asset-edges replaces PUT /api/asset-edges
*** The parameters "sourceType" and "targetType" now use enumeration values
* Resources
** all endpoints in "v1" were marked as deprecated
*** The parameter "modelSegment" now uses enumeration values
* Risks
** GET /api/v2/risks replaces GET /api/risks/{managementSystemId}
*** The path parameter "managementSystemId" was removed. Instead you can now use the optional query parameters "managementSystemId" and "includePublicRisks" to retrieve and filter risks.
** GET /api/v2/risks/{id} replaces GET /api/risks/byKey/{id}
*** Endpoints were adjusted to be consistent with the other endpoints.
** PUT /api/v2/risks replaces PUT /api/risks
*** The data-model was adjusted. The "managementSystemId" is not set at top level but per risk. The model is now "RiskCreateOrUpdateDtoV2" not "HazardSituationImportDto"
*** It is now possible to modify the state of a risk via the api. Valid values are: Active, Inactive, Accepted, Rejected
*** It is now possible to modify the strategy of a risk via the api. The permitted values depend on whether a severity or an benefit has been assigned (i.e. whether it is a risk or an opportunity). If it is a severity, the permitted values are: Undefined, Avoidance, Reduction, Transfer, Acceptance. If it is a benefit, the permitted values are: Undefined, Enhance, Share, Exploit, Ignore.
*** It is now possible to edit the risk remarks
*** It is now possible to change the advisor of the risk
** POST /api/v2/risks/submit new endpoint for importing risks in state "Submitted"
** DELETE /api/v2/risks/{id} replaces DELETE /api/risks/{id}
** all endpoints in "v1" were marked as deprecated
** GET endpoints return more information about the risk such as remarks, strategy and advisors.

All other endpoints are still offered in "v1". Before "v1" is really removed, all endpoints will be offered through "v2".

== ApiKeys ==

All endpoints of the REST API are secured via ApiKeys!

In order for requests to the REST API to be accepted, a valid ApiKey must be sent in the authorization header of each request.

ApiKeys can only be created by Administrators on their profile (click on the profile picture). Each Administrator can have only one valid ApiKey at any time.

[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Section to manage ApiKey]]

ApiKeys can be created with an expiration date. When the ApiKey expires, no more requests can be made with it.

[[Datei:REST API ApiKey generieren.png|thumb|left|900px| Generate ApiKey ]]

The ApiKey is shown only once! If you do not copy it at that moment, you need to create a new ApiKey. By clicking on the button to the left of the ApiKey, the ApiKey will be copied to your clipboard. Make sure that you save the ApiKey in a safe location.

[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| Copy ApiKey ]]

An Administrator can revoke their own ApiKey at any time, which means that no more requests can be made via that ApiKey afterwards.

[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| Revoke ApiKey]]

To manage ApiKeys, it is recommended to create an Administrator for each application that controls the REST API and thus to obtain an ApiKey for each application. This way, access can be taken away from an application at any time.