# Rest API

## Xygeni REST API

The Xygeni API is based on the OpenAPI ("Swagger") standards and allows retrieval of security issues, project risk summary, trends in security position, and report generation, plus administration.

{% hint style="info" %}
The api base URL is [**https://api.xygeni.io**](https://api.xygeni.io/)
{% endhint %}

### API Endpoints

Most Xygeni API endpoints return JSON output.

The easiest way to find the endpoint for a particular need is by browsing in the [online API documentation](https://api.xygeni.io/swagger-ui/index.html).

### Generating an API client

Instead of providing a downloadable client for different platforms / languages, it is recommended to generate the client from the OpenAPI specification (if you trust the publicly available generators). This allows it to control the generation of the client, and keeps it updated to the latest API version.

For generating an api client for a target programming language, the OpenAPI / Swagger specification can be downloaded from <https://get.xygeni.io/latest/swagger/swagger.yaml> (YAML) or <https://get.xygeni.io/latest/swagger/swagger.json> (JSON).

{% tabs %}
{% tab title="For Unix / MacOS" %}

```
curl https://get.xygeni.io/latest/swagger/swagger.yaml xygeni-api.yaml
```

{% endtab %}

{% tab title="For Windows" %}

```
iwr -OutFile xygeni-api.yaml https://get.xygeni.io/latest/swagger/swagger.yaml
```

{% endtab %}
{% endtabs %}

#### Method 1: Using Swagger editor

The most interactive way to create a client from a swagger file is using the online swagger editor. Go to Use <https://editor-next.swagger.io/>. Select file, import URL and type in the URL of the Xygeni API URL. Alternatively you can select `File`, *Import File* and upload the downloaded *swagger.yaml* file.

Next select `Generate Client` and select the language of your choice. The end result is a zip file you can download with the generated client code.

#### Method 2: Using swagger-codegen

Instead of using the interactive editor, you may use the [swagger-codegen](https://github.com/swagger-api/swagger-codegen). This is the recommended alternative in general, as it provides much more control on the generated client code.

#### Method 3: Using OpenAPI Generator

[OpenAPI Generator](https://openapi-generator.tech/) is another nice client generator for api clients from OpenAPI / Swagger documents.

You may download the [`openapi-generator-cli.jar`](https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.2.1/openapi-generator-cli-6.2.1.jar) and run its help command:

```shell
# For Unix / macOS
curl https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.2.1/openapi-generator-cli-6.2.1.jar -O openapi-generator-cli.jar

# For Windows
iwr -OutFile openapi-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.2.1/openapi-generator-cli-6.2.1.jar

java -jar openapi-generator-cli.jar config-help -g java
```

There are [other alternatives](https://openapi-generator.tech/docs/installation/) that wrap the Java-based OpenAPI generator CLI, that you may try for convenience. You may then replace `java -jar openapi-generator-cli.jar` with `openapi-generator-cli` command, for example.

It is recommended to define a [configuration file](https://openapi-generator.tech/docs/configuration) like `my_config.yaml` with options for your language of choice, and then call the generator with the config file:

```shell
openapi-generator-cli generate -i xygeni-api.yaml -g typescript-fetch -o out \
    -c config.yaml
```

### Usage

An api client generated for your language of choice could be convenient. Alternatively, there are popular frameworks for invoking api endpoints that could be used. A third option is to use a command-line tool like `curl` or `wget`.

The [online API documentation](https://api.xygeni.io/swagger-ui.html) is the reference to the available endpoints.

#### Authentication

Most API endpoints require authentication (except `/ping` to check for platform availability). The recommended way to authenticate operations is using an access token (also known as `apikey` or `API token`). Go to [Generate Access Token](https://docs.xygeni.io/platform-administration/profile#generate_token_for_scanner-1) for full details.

Authenticating api calls require an Authorization header: `Authorization: Bearer <TOKEN_HERE>`.

Let’s assume that the access token is set in the `XYGENI_TOKEN` environment variable. The following is an example using `curl` for the [`/secret`](https://api.xygeni.io/swagger-ui.html#/Secrets) endpoint:

```bash
curl -s -H "Authorization: Bearer ${XYGENI_TOKEN}" -L "{api_key}/secret/"
```

```console
{
  "secrets": [
    {
      "id": 41,
      "detector": {
        "code": "atlassian_oauth2_key",
        "type": "access_key",
        "description": "Access Key"
      },
      "endLine": 3,
...
```

The Xygeni API may also use basic authentication with username and password, but it is not recommended. Use an access token instead.

An example of basic authentication with curl on the same endpoint:

```shell
curl -s -u "USERNAME:PASSWORD" -L "https://api.xygeni.io/secret/"
```

{% hint style="info" %}
As a shorthand, in the following examples, a `XY_API_TOK` environment variable with value `Authorization: Bearer ${XYGENI_TOKEN}` will be used.
{% endhint %}

#### Fetching data

Most endpoints for fetching issues need a `projectId` parameter. The list of project IDs for the organization’s projects could be fetched using the [GET /projects/list](https://api.xygeni.io/swagger-ui.html#!/project45controller/listProjectsUsingGET) endpoint:

```shell
curl -s -H "$XY_API_TOK" https://api.xygeni.io/projects/list
```

The [Analysis](https://api.xygeni.io/swagger-ui.html#/Analysis) endpoints could be used to fetch data for the different issue types. For example, to get the latest misconfigurations:

```asciidoc
curl -s -H "$XY_API_TOK" {api_url}/misconfigurations
```

#### Administration

**Create projects**

For automation, you may need to create projects. The [POST /project/create](https://api.xygeni.io/swagger-ui.html#!/project45controller/insertProjectUsingPOST) endpoint creates a project.

{% hint style="info" %}
You need MANAGER\_PROJECT or ROOT roles for creating projects for your organization.
{% endhint %}

**Delete project**

Sometimes projects terminate, software is decommissioned or replaced, and so on. The [DELETE /project/{projectId}](https://api.xygeni.io/swagger-ui.html#!/project45controller/deleteProjectUsingDELETE) allows us to remove a given project **AND ALL ITS DATA**.

{% hint style="info" %}
This is a destructive operation. Project data is removed from the platform.
{% endhint %}