Using the API

Document Static Analysis

You can access GUARDARA's static analysis feature to identify a variety of issues affecting your documentation or your web service implementation directly using the API.

Request

All request examples require the following environment variables to be set.

Environment Variable	Description
GUARDARA_ADDRESS	The IP address or fully qualified domain name (FQDN) of GUARDARA Manager.
API_KEY	The API Key to authenticate to GUARDARA.

Submitting the Document URL

You can validate your documents by submitting the URL of the document to GUARDARA as shown below.

cURL
NodeJS
Python

curl -k -X POST "https://${GUARDARA_ADDRESS}:8443/api/conversion/openapi/validate/url" \
    --header "Authorization: Bearer ${API_KEY}" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "url": "https://gitlab.com/guardara-community/demos-and-tutorials/tutorial-web-service-testing/-/raw/master/openapi.v1.yml"
    }'

const request = require('request');

const url = `https://${process.env.GUARDARA_ADDRESS}:8443/api/conversion/openapi/validate/url`;
const documentURL = 'https://gitlab.com/guardara-community/demos-and-tutorials/tutorial-web-service-testing/-/raw/master/openapi.v1.yml';

const headers = {
    'Authorization': `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json'
};

const options = {
    method: 'POST',
    url,
    headers,
    body: JSON.stringify({ "url": documentURL })
};

request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

#!/usr/bin/env python3

from os import getenv
from json import dumps
from requests import request

url = f"https://{getenv('GUARDARA_ADDRESS')}:8443/api/conversion/openapi/validate/url"

payload = dumps({
  "url": "https://gitlab.com/guardara-community/demos-and-tutorials/tutorial-web-service-testing/-/raw/master/openapi.v1.yml"
})
headers = {
  "Authorization": f"Bearer {getenv('API_KEY')}",
  "Content-Type": "application/json"
}

response = request("POST", url, headers=headers, data=payload, verify=False)

print(response.text)

Uploading the Document

You can validate your documents by uploading them to GUARDARA as shown below.

cURL
NodeJS
Python

Please note that you have to update the document's path to reflect the location of your document.

curl -k -X POST "https://${GUARDARA_ADDRESS}:8443/api/conversion/openapi/validate" \
    --header "Authorization: Bearer ${API_KEY}" \
    --form 'file=@"/webservice/openapi.v1.yml"'

Please note that you have to update the documentLocation variable's value to reflect the location of your document.

const request = require('request');
const fs = require('fs');

const url = `https://${process.env.GUARDARA_ADDRESS}:8443/api/conversion/openapi/validate`;
const documentLocation = '/webservice/openapi.v1.yml';

const headers = {
    'Authorization': `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json'
};

const formData = {
    file: {
        value: fs.createReadStream(documentLocation),
        options: {
            filename: 'openapi.v1.yml',
            contentType: null
        }
    }
};

const options = {
    method: 'POST',
    url,
    headers,
    formData
};

request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

Please note that you have to update the DOCUMENT_LOCATION variable's value to reflect the location of your document.

#!/usr/bin/env python3

from os import getenv
from requests import request

DOCUMENT_LOCATION = "/webservice/openapi.v1.yml"
url = f"https://{getenv('GUARDARA_ADDRESS')}:8443/api/conversion/openapi/validate"

files=[
    (
        'file',
        ('openapi.v1.yml',open(DOCUMENT_LOCATION,'rb'),
        'application/octet-stream')
    )
]

headers = {
  "Authorization": f"Bearer {getenv('API_KEY')}"
}

response = request("POST", url, headers=headers, data={}, files=files, verify=False)
print(response.text)

Response

GUARDARA returns a JSON object with three properties. These are summarized in the table below.

Property	Value
status	`success` if the validation was successful, `error` in case the document could not be validated.
result	A list of issues identified by GUARDARA by analysing the OpenAPI document.
swaggerValidationResults	A list of errors reported by the OpenAPI/Swagger file processing library (swagger-parser) used by GUARDARA to load the document.

An example response is shown below.

{
    "status": "success",
    "result": [
        {
            "id": "plaintext-communication",
            "name": "Plaintext Communication",
            "category": "security",
            "severity": "high",
            "operation": null,
            "problem": "The server did not utilize HTTPS when transmitting data: http://127.0.0.1:4141/v1.",
            "impact": "A malicious actor could intercept the network traffic and obtain sensitive information.",
            "recommendation": "It is highly recommended use the HTTPS protocol to encrypt the network traffic using TLS."
        },
        {
            "id": "missing-response-schema",
            "name": "Missing Response Schema Definition for 2xx Response Code",
            "category": "documentation",
            "severity": "high",
            "operation": "createUser",
            "problem": "No response body schema was defined for responses with a 2xx response code.",
            "impact": "GUARDARA will assume that the response body conforms to the schema specified for the request body.",
            "recommendation": "It is highly recommended to explicitly document and set the response schema for responses with 2xx response code."
        }
    ],
    "swaggerValidationResults": [
        {
            "instancePath": "/paths/~1user~1{id}/get",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "responses"
            },
            "message": "must have required property 'responses'"
        },
        {
            "instancePath": "/paths/~1user~1{id}/delete",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "responses"
            },
            "message": "must have required property 'responses'"
        }
    ]
}

Document Processing

Request

The request examples require the following environment variables to be set.

Environment Variable	Description
GUARDARA_ADDRESS	The IP address or fully qualified domain name (FQDN) of GUARDARA Manager.
API_KEY	The API Key to authenticate to GUARDARA.
ENGINE_ID	The ID of the Engine to assign the test to.

The optional config object can be used to influence the test configuration generation. The table below documents the supported options.

Option	Description
engineId	The ID of the Engine to assign the test to. In the examples below, the value is fetched from the `ENGINE_ID` environment variable mentioned above.

Submitting the Document URL

You can import your documents by submitting the URL of the document to GUARDARA as shown below.

cURL
NodeJS
Python

curl -k -X POST "https://${GUARDARA_ADDRESS}:8443/api/conversion/openapi/import/url" \
    --header "Authorization: Bearer ${API_KEY}" \
    --header 'Content-Type: application/json' \
    --data-raw "{
        \"url\": \"https://gitlab.com/guardara-community/demos-and-tutorials/tutorial-web-service-testing/-/raw/master/openapi.v1.yml\",
        \"config\": {\"engineId\": \"${ENGINE_ID}\"}
    }"

const request = require('request');

const url = `https://${process.env.GUARDARA_ADDRESS}:8443/api/conversion/openapi/import/url`;
const documentURL = 'https://gitlab.com/guardara-community/demos-and-tutorials/tutorial-web-service-testing/-/raw/master/openapi.v1.yml';

const headers = {
    'Authorization': `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json'
};

const requestBody = { 
    url: documentURL,
    config: {
        engineId: process.env.ENGINE_ID,
    }
};

const options = {
    method: 'POST',
    url,
    headers,
    body: JSON.stringify(requestBody)
};

request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

#!/usr/bin/env python3

from os import getenv
from json import dumps
from requests import request

url = f"https://{getenv('GUARDARA_ADDRESS')}:8443/api/conversion/openapi/import/url"

payload = dumps({
    "url": "https://gitlab.com/guardara-community/demos-and-tutorials/tutorial-web-service-testing/-/raw/master/openapi.v1.yml",
    "config": {
        "engineId": getenv("ENGINE_ID")
    }
})
headers = {
    "Authorization": f"Bearer {getenv('API_KEY')}",
    "Content-Type": "application/json"
}

response = request("POST", url, headers=headers, data=payload, verify=False)

print(response.text)

Uploading the Document

You can validate your documents by uploading them to GUARDARA as shown below.

cURL
NodeJS
Python

Please note that you have to update the document's path to reflect the location of your document.

curl -k -X POST "https://${GUARDARA_ADDRESS}:8443/api/conversion/openapi/import" \
    --header "Authorization: Bearer ${API_KEY}" \
    --form 'file=@"/webservice/openapi.v1.yml"' \
    --form "config=\"{\\\"engineId\\\": \\\"${ENGINE_ID}\\\"}\";type=application/json"

Please note that you have to update the documentLocation variable's value to reflect the location of your document.

const request = require('request');
const fs = require('fs');

const url = `https://${process.env.GUARDARA_ADDRESS}:8443/api/conversion/openapi/import`;
const documentLocation = '/webservice/openapi.v1.yml';

const headers = {
    'Authorization': `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json'
};

const formData = {
    file: {
        value: fs.createReadStream(documentLocation),
        options: {
            filename: 'openapi.v1.yml',
            contentType: null
        }
    },
    config: `{"engineId": "${process.env.ENGINE_ID}"}`
};

const options = {
    method: 'POST',
    url,
    headers,
    formData
};

request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

Please note that you have to update the DOCUMENT_LOCATION variable's value to reflect the location of your document.

#!/usr/bin/env python3

from os import getenv
from json import dumps
from requests import request

DOCUMENT_LOCATION="/webservice/openapi.v1.yml"
url = f"https://{getenv('GUARDARA_ADDRESS')}:8443/api/conversion/openapi/import"
config = {"engineId": getenv("ENGINE_ID")}

files = {
  'file': ('openapi.v1.yml', open(DOCUMENT_LOCATION, 'rb'), 'application/octet-stream'),
  'config': (None, dumps(config), 'application/json')
}

headers = {
  "Authorization": f"Bearer {getenv('API_KEY')}"
}

response = request("POST", url, headers=headers, files=files, verify=False)

print(response.text)

Response

GUARDARA returns a JSON object with two properties. These are summarized in the table below.

Property	Value
projects	A list of projects created during document processing.
errors	A list of errors encountered while processing the OpenAPI document.

An example response is shown below.

{
    "projects": [
        {
            "version": 1,
            "type": "project",
            "group": "395d271c-f07b-4456-8959-9263cd7073b3",
            "flow": "24d00884-c497-44e1-9c64-0766588e2762",
            "name": "createUser",
            "description": "",
            "engine": "test",
            "distributed": false,
            "driver": "network_tcp_http",
            "session": {
                "type": "web",
                "performance_monitoring": true,
                "analyze_on_finding": true,
                "analyze_restart_timeout_soft": 10,
                "analyze_restart_timeout_hard": 300,
                "start_paused": false,
                "delete_on_completed": true,
                "performance_report_percent": 5000,
                "performance_baseline_iterations": 100,
                "run_web_sanity_check": true,
                "run_web_auth_check": true
            },
            "monitors": [],
            "targets": [
                {
                    "name": "http://127.0.0.1:4141",
                    "driver": {
                        "scheme": "HTTP",
                        "address": "127.0.0.1",
                        "port": 4141,
                        "tls_certificate": "",
                        "tls_key": "",
                        "tls_ca": "",
                        "tls_validation": false
                    },
                    "monitors": [],
                    "variables": null,
                    "authentication": [
                        {
                            "name": "api_key",
                            "description": "API key for authentication",
                            "default": "",
                            "sensitive": true
                        }
                    ]
                }
            ],
            "variables": "cac3ea90-a6a4-47fa-89cb-0f45590233ef",
            "createdAt": "2022-09-03T05:04:19.411Z",
            "updatedAt": "2022-09-03T05:04:19.411Z",
            "id": "2a4c61af-99e1-4b69-9933-46d360829bd3",
            "children": []
        }
    ],
    "errors": [
        {
            "id": "operation-responses-missing",
            "name": "Missing Operation Response Definition",
            "category": "documentation",
            "severity": "high",
            "operation": "getUserById",
            "problem": "The expected responses of the operation were not documented.",
            "impact": "In a production environment this can lead to difficulties setting up integrations and broken features. GUARDARA will not be able to validate the responses received against the OpenAPI documentation when testing the operation.",
            "recommendation": "Please correct the OpenAPI document so that the operation responses are documented using the [Responses Object](https://swagger.io/specification/#responses-object). GUARDARA requires at least 200 OK responses to be documented with at least one content-type defined."
        }
    ]
}

Something's not right? Let us know!

Using the API

Document Static Analysis​

Request​

Submitting the Document URL​

Uploading the Document​

Response​

Document Processing​

Request​

Submitting the Document URL​

Uploading the Document​

Response​

Document Static Analysis

Request

Submitting the Document URL

Uploading the Document

Response

Document Processing

Request

Submitting the Document URL

Uploading the Document

Response