1 of 9

API How-Tos

IONOS API Gateway APIs allow contract owners, administrators, and authenticated users with the required permissions to create and configure your API to manage routes, integrate backend services, and deploy your API.

Quick Links

Create Gateway

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

API Gateway is a regional service. To create an instance, you should send a POST request to the appropriate regional endpoint, e.g., Berlin https://apigateway.de-txl.ionos.com

Request

Result: On a successful POST request, you receive a response containing the API Gateway ID and the API Gateway details.

Response

201 Gateway successfully created

Retrieve Gateway

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To retrieve the Gateway, you need to use the following GET request:

GET /gateways/{apigatewayId}

Request

curl -X 'GET' \
  'https://apigateway.de-txl.ionos.com/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00' \
  -H 'accept: application/json'

Response

201 Success

{
  "id": "0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "type": "gateway",
  "href": "/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "john.doe@example.com",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "john.doe@example.com",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "publicEndpoint": "jf8u4tgr73sd-ag.87uhr654gq90.apigateway.de-txl.ionos.com"
  },
  "properties": {
    "name": "APIGateway 1",
    "logs": false,
    "metrics": false,
    "customDomains": [
      {
        "name": "api.example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003"
      }
    ]
  }
}

Ensure Gateway

The command ensures the Gateway with the provided ID is created or modified. The full Gateway must be provided to ensure (either update or create) the Gateway. Non-present data will only be filled with defaults or left empty, but previous values will not be taken into consideration.

To ensure the Gateway, you need to use the following PUT request:

PUT /gateways/{apigatewayId}

Request

curl -X 'PUT' \
  'https://apigateway.de-txl.ionos.com/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {},
  "properties": {
    "name": "APIGateway 1",
    "logs": false,
    "metrics": false,
    "customDomains": [
      {
        "name": "api.example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003"
      }
    ]
  }
}'

Response

200 Gateway successfully updated

{
  "id": "0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "type": "gateway",
  "href": "/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "john.doe@example.com",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "john.doe@example.com",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "publicEndpoint": "jf8u4tgr73sd-ag.87uhr654gq90.apigateway.de-txl.ionos.com"
  },
  "properties": {
    "name": "APIGateway 1",
    "logs": false,
    "metrics": false,
    "customDomains": [
      {
        "name": "api.example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003"
      }
    ]
  }
}

201 Gateway successfully ensured

{
  "id": "0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "type": "gateway",
  "href": "/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "john.doe@example.com",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "john.doe@example.com",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "publicEndpoint": "jf8u4tgr73sd-ag.87uhr654gq90.apigateway.de-txl.ionos.com"
  },
  "properties": {
    "name": "APIGateway 1",
    "logs": false,
    "metrics": false,
    "customDomains": [
      {
        "name": "api.example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003"
      }
    ]
  }
}

Delete Gateway

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To delete the specified Gateway, you need to use the following DELETE request:

DELETE /gateways/{apigatewayId}

Request

curl -X 'DELETE' \
  'https://apigateway.de-txl.ionos.com/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00' \
  -H 'accept: application/json'

Result: On a successful DELETE request, you receive a response 202 - Successful.

Response

202 Deleting Gateway was successful

Create Route

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To create the object, the full route needs to be provided. Optional data will be filled with defaults or left empty.

To create a new route, you need to use the following POST request:

POST /gateways/{apigatewayId}/routes

Request

Response

201 Route successfully created

Retrieve Route

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To retrieve the route, you need to use the following GET request:

GET /gateways/{apigatewayId}/routes/{routeId}

Request

Response

200 Success

Ensure Route

The command ensures that the route with the provided ID is created or modified. The full route must be provided to ensure (either update or create) the route. Non-present data will only be filled with defaults or left empty, but previous values will not be taken into consideration.

To ensure the route, you need to use the following PUT request:

PUT /gateways/{apigatewayId}/routes/{routeId}

Request

Response

200 Route successfully updated

201 Route successfully ensured

Delete Route

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To delete the specified route, you need to use the following DELETE request:

DELETE /gateways/{apigatewayId}/routes/{routeId}

Request

Result: On a successful DELETE request, you receive a response 202 - Successful.

Response

202 Deleting Route was successful

Ensure Gateway

To ensure the Gateway, you need to use the following PUT request:

PUT /gateways/{apigatewayId}

Request

curl -X 'PUT' \
  'https://apigateway.de-txl.ionos.com/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {},
  "properties": {
    "name": "APIGateway 1",
    "logs": false,
    "metrics": false,
    "customDomains": [
      {
        "name": "api.example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003"
      }
    ]
  }
}'

Response

200 Gateway successfully updated

{
  "id": "0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "type": "gateway",
  "href": "/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "john.doe@example.com",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "john.doe@example.com",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "publicEndpoint": "jf8u4tgr73sd-ag.87uhr654gq90.apigateway.de-txl.ionos.com"
  },
  "properties": {
    "name": "APIGateway 1",
    "logs": false,
    "metrics": false,
    "customDomains": [
      {
        "name": "api.example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003"
      }
    ]
  }
}

201 Gateway successfully ensured

{
  "id": "0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "type": "gateway",
  "href": "/gateways/0620c174-dd3c-5eb4-87c8-e2b516553a00",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "john.doe@example.com",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "john.doe@example.com",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "publicEndpoint": "jf8u4tgr73sd-ag.87uhr654gq90.apigateway.de-txl.ionos.com"
  },
  "properties": {
    "name": "APIGateway 1",
    "logs": false,
    "metrics": false,
    "customDomains": [
      {
        "name": "api.example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003"
      }
    ]
  }
}

Ensure Route

To ensure the route, you need to use the following PUT request:

PUT /gateways/{apigatewayId}/routes/{routeId}

Request

Response

200 Route successfully updated

{
  "id": "50982018-bb17-5cb9-bcd4-97f8bbc7dc23",
  "type": "route",
  "href": "/gateways/{apigatewayId}/routes/50982018-bb17-5cb9-bcd4-97f8bbc7dc23",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "john.doe@example.com",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "john.doe@example.com",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "publicEndpoint": "jf8u4tgr73sd-ag.87uhr654gq90.apigateway.de-txl.ionos.com"
  },
  "properties": {
    "name": "example-route",
    "type": "http",
    "paths": [
      "/foo/*",
      "/bar"
    ],
    "methods": [
      "GET",
      "POST"
    ],
    "websocket": false,
    "upstreams": [
      {
        "scheme": "http",
        "loadbalancer": "roundrobin",
        "host": "www.example.com",
        "port": 80,
        "weight": 100
      }
    ]
  }
}

201 Route successfully ensured

{
  "id": "50982018-bb17-5cb9-bcd4-97f8bbc7dc23",
  "type": "route",
  "href": "/gateways/{apigatewayId}/routes/50982018-bb17-5cb9-bcd4-97f8bbc7dc23",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "john.doe@example.com",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "john.doe@example.com",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "publicEndpoint": "jf8u4tgr73sd-ag.87uhr654gq90.apigateway.de-txl.ionos.com"
  },
  "properties": {
    "name": "example-route",
    "type": "http",
    "paths": [
      "/foo/*",
      "/bar"
    ],
    "methods": [
      "GET",
      "POST"
    ],
    "websocket": false,
    "upstreams": [
      {
        "scheme": "http",
        "loadbalancer": "roundrobin",
        "host": "www.example.com",
        "port": 80,
        "weight": 100
      }
    ]
  }
}