Skip to main content

Get an Ingress

GET/v2/ingresses/{ingressId}
API version
v2
Request method
GET
Operation ID
ingress-get-ingress

Request​

  • ingressIdstring (uuid)required

    ID of the Ingress to be retrieved.

Responses​

Format
application/json
Description

OK

  • dnsValidationErrorsarray of string (one of: ERROR_UNSPECIFIED, ERROR_QUAD_A, ERROR_NO_A_RECORD, ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED)required

    A list of errors that occurred while validating the ingress's dns before requesting a certificate. ERROR_QUAD_A and ERROR_NO_A_RECORD are deprecated and no longer reported.

    • Array[
      • *string (one of: ERROR_UNSPECIFIED, ERROR_QUAD_A, ERROR_NO_A_RECORD, ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED)
      ]
  • hostnamestring (idn-hostname)required
  • idstring (uuid)required
  • ipsobjectrequired
    • v4array of string (ipv4)required
      • Array[
        • *string (ipv4)
        ]
    • v6array of string (ipv6)required
      • Array[
        • *string (ipv6)
        ]
  • isDefaultbooleanrequired

    Whether this ingress is the default ingress or not. A default ingress is automatically created, it cannot be deleted. There can be only one default ingress per project.

  • isDomainboolean
  • isEnabledbooleanrequired
  • ownershipobjectrequired
    • txtRecordstring
    • verifiedbooleanrequired

      Whether the domain ownership is verified or not.

  • pathsarray of objectrequired

    A list of paths. The default path / is always present and cannot be removed.

    • Array[
      • *object
        • pathstringrequired
        • targetone of 4 alternativesrequired
          • Alternativeobject

            Redirect requests to this path to another URL

            • urlstring (uri)required

              The URL to which requests should be forwarded.

          • Alternativeobject

            Serve a specific app installation

            • installationIdstring (uuid)required

              The ID of an app installation within the same project to which requests should be forwarded.

          • Alternativeobject

            Serve a generic default page

            • useDefaultPagebooleanrequired

              Set this to true to serve a generic default site at this path.

          • Alternativeobject

            Forward requests to this path to a specific container.

            • containerobjectrequired
              • idstring (uuid)required
              • portProtocolstring (docker-network-port)required

                docker-compose port specification in format port/protocol (e.g. 8080/TCP)

      ]
  • projectIdstring (uuid)required
  • senderLoginProtectionboolean

    If enabled, only mailboxes of the Ingress's Project may send emails from addresses of the Ingress and its SubIngresses. Only set on the root Ingress, as it covers all of its SubIngresses.

  • tlsone of 2 alternativesrequired
    • Alternativeobject
      • acmebooleanrequired

        Has to be true, as ssl cannot be deactivated.

      • isCreatedbooleanrequired
      • requestDeadlinestring (date-time)
    • Alternativeobject
      • certificateIdstring (uuid)required
Content-Type: application/json

{
  "dnsValidationErrors": [
    "ERROR_UNSPECIFIED"
  ],
  "hostname": "some-hostname.example",
  "id": "f0f86186-0a5a-45b2-aa33-502777496347",
  "ips": {
    "v4": [
      "string"
    ],
    "v6": [
      "string"
    ]
  },
  "isDefault": true,
  "isDomain": true,
  "isEnabled": true,
  "ownership": {
    "txtRecord": "string",
    "verified": true
  },
  "paths": [
    {
      "path": "string",
      "target": {
        "url": "https://redirect-target.example"
      }
    }
  ],
  "projectId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "senderLoginProtection": true,
  "tls": {
    "acme": true,
    "isCreated": true,
    "requestDeadline": "1985-10-26T01:21:00.000Z"
  }
}
{
  "properties": {
    "dnsValidationErrors": {
      "description": "A list of errors that occurred while validating the ingress's dns before requesting a certificate. `ERROR_QUAD_A` and `ERROR_NO_A_RECORD` are deprecated and no longer reported.",
      "items": {
        "enum": [
          "ERROR_UNSPECIFIED",
          "ERROR_QUAD_A",
          "ERROR_NO_A_RECORD",
          "ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED"
        ],
        "type": "string"
      },
      "type": "array"
    },
    "hostname": {
      "format": "idn-hostname",
      "type": "string"
    },
    "id": {
      "format": "uuid",
      "type": "string"
    },
    "ips": {
      "properties": {
        "v4": {
          "items": {
            "format": "ipv4",
            "type": "string"
          },
          "type": "array"
        },
        "v6": {
          "items": {
            "format": "ipv6",
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "v4",
        "v6"
      ],
      "type": "object"
    },
    "isDefault": {
      "description": "Whether this ingress is the default ingress or not. A default ingress is automatically created, it cannot be deleted. There can be only one default ingress per project.",
      "type": "boolean"
    },
    "isDomain": {
      "type": "boolean"
    },
    "isEnabled": {
      "type": "boolean"
    },
    "ownership": {
      "properties": {
        "txtRecord": {
          "type": "string"
        },
        "verified": {
          "description": "Whether the domain ownership is verified or not.",
          "type": "boolean"
        }
      },
      "required": [
        "verified"
      ],
      "type": "object"
    },
    "paths": {
      "description": "A list of paths. The default path `/` is always present and cannot be removed.",
      "items": {
        "properties": {
          "path": {
            "type": "string"
          },
          "target": {
            "oneOf": [
              {
                "properties": {
                  "url": {
                    "format": "uri",
                    "type": "string",
                    "description": "The URL to which requests should be forwarded.",
                    "example": "https://redirect-target.example"
                  }
                },
                "required": [
                  "url"
                ],
                "type": "object",
                "description": "Redirect requests to this path to another URL"
              },
              {
                "properties": {
                  "installationId": {
                    "format": "uuid",
                    "type": "string",
                    "description": "The ID of an app installation within the same project to which requests should be forwarded."
                  }
                },
                "required": [
                  "installationId"
                ],
                "type": "object",
                "description": "Serve a specific app installation"
              },
              {
                "properties": {
                  "useDefaultPage": {
                    "type": "boolean",
                    "description": "Set this to `true` to serve a generic default site at this path."
                  }
                },
                "required": [
                  "useDefaultPage"
                ],
                "type": "object",
                "description": "Serve a generic default page"
              },
              {
                "properties": {
                  "container": {
                    "properties": {
                      "id": {
                        "format": "uuid",
                        "type": "string"
                      },
                      "portProtocol": {
                        "description": "docker-compose port specification in format port/protocol (e.g. 8080/TCP)",
                        "format": "docker-network-port",
                        "type": "string",
                        "example": "80/tcp"
                      }
                    },
                    "required": [
                      "id",
                      "portProtocol"
                    ],
                    "type": "object",
                    "descriptions": "References a specific port/container combination within the same project."
                  }
                },
                "required": [
                  "container"
                ],
                "type": "object",
                "description": "Forward requests to this path to a specific container."
              }
            ]
          }
        },
        "required": [
          "path",
          "target"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "projectId": {
      "format": "uuid",
      "type": "string"
    },
    "senderLoginProtection": {
      "description": "If enabled, only mailboxes of the Ingress's Project may send emails from addresses of the Ingress and its SubIngresses. Only set on the root Ingress, as it covers all of its SubIngresses.",
      "type": "boolean"
    },
    "tls": {
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "acme": {
              "description": "Has to be `true`, as ssl cannot be deactivated.",
              "type": "boolean"
            },
            "isCreated": {
              "type": "boolean"
            },
            "requestDeadline": {
              "format": "date-time",
              "type": "string"
            }
          },
          "required": [
            "acme",
            "isCreated"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "certificateId": {
              "format": "uuid",
              "type": "string"
            }
          },
          "required": [
            "certificateId"
          ],
          "type": "object"
        }
      ]
    }
  },
  "required": [
    "id",
    "hostname",
    "projectId",
    "isDefault",
    "tls",
    "paths",
    "isEnabled",
    "ips",
    "dnsValidationErrors",
    "ownership"
  ],
  "type": "object"
}

Usage examples​

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/ingresses/f0f86186-0a5a-45b2-aa33-502777496347
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
  
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.domain.ingressGetIngress({
  "ingressId": "f0f86186-0a5a-45b2-aa33-502777496347"
});

assertStatus(response, 200);
  
use \Mittwald\ApiClient\Generated\V2\Clients\Domain\IngressGetIngress\IngressGetIngressRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new IngressGetIngressRequest(
  ingressId: "f0f86186-0a5a-45b2-aa33-502777496347"
));
$response = $client->domain()->ingressGetIngress($request);

var_dump($response->getBody();

On this page