Routes

A route is a rule that maps an incoming request to a specific backend service.

This tag groups all operations for routes.

Retrieve all Routes

get

This endpoint enables retrieving all Routes using pagination and optional filters.

Authorizations

Path parameters

apigatewayIdstring · uuidRequired

The ID (UUID) of the Gateway.

Example: 0620c174-dd3c-5eb4-87c8-e2b516553a00

Query parameters

offsetinteger · int32Optional

The first element (of the total list of elements) to include in the response. Use together with limit for pagination.

Default: 0Example: 0

limitinteger · int32 · min: 1 · max: 1000Optional

The maximum number of elements to return. Use together with offset for pagination.

Default: 100Example: 100

orderBystring · enumOptional

The field to order the results by. If not provided, the results will be ordered by the default field.

Default: -createdDatePossible values:

Responses

200

Returned all requested Routes successfully.

application/json

Responseall of

and

400

### Bad Request The request send to the API was malformed.

application/json

401

### Unauthorized The request is missing authorization information or the authorization information provided are expired.

application/json

403

### Not Allowed The user issuing the request does not have the needed permissions.

application/json

429

### Too Many Requests The user has sent too many requests in a given amount of time.

application/json

500

### Internal Server Error An internal error occurred. We apologize for the inconvenience!

application/json

503

### Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

application/json

default

### Unexpected Internal Server Error An unexpected internal error occurred. We apologize for the inconvenience!

application/json

get

HTTPcURLJavaScriptPython

GET /gateways/{apigatewayId}/routes HTTP/1.1
Host: apigateway.de-txl.ionos.com
Authorization: Bearer JWT
Accept: */*

{
  "id": "38ec142f-7b7b-5707-83ba-4db7f8286cfb",
  "type": "collection",
  "href": "/gateways/{apigatewayId}/routes",
  "items": [
    {
      "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": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "lastModifiedDate": "2020-12-11T13:37:50+01:00",
        "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "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
          }
        ],
        "cache": {
          "enable": true,
          "httpMethods": [
            "GET"
          ],
          "httpCodes": [
            200
          ]
        }
      }
    }
  ],
  "offset": 0,
  "limit": 42,
  "_links": {
    "prev": "http://PREVIOUS-PAGE-URI",
    "self": "http://THIS-PAGE-URI",
    "next": "http://NEXT-PAGE-URI"
  }
}

Create Route

post

Creates a new Route.

The full Route needs to be provided to create the object. Optional data will be filled with defaults or left empty.

Authorizations

Path parameters

apigatewayIdstring · uuidRequired

The ID (UUID) of the Gateway.

Example: 0620c174-dd3c-5eb4-87c8-e2b516553a00

Body

metadataanyOptional

Metadata

Responses

201

Route successfully created.

application/json

400

### Bad Request The request send to the API was malformed.

application/json

401

### Unauthorized The request is missing authorization information or the authorization information provided are expired.

application/json

403

### Not Allowed The user issuing the request does not have the needed permissions.

application/json

415

### Unsupported Media Type The request has an unsupported media type.

application/json

422

### Unprocessable Entity The request was well-formed but was unable to be followed due to semantic errors.

application/json

429

### Too Many Requests The user has sent too many requests in a given amount of time.

application/json

500

### Internal Server Error An internal error occurred. We apologize for the inconvenience!

application/json

503

### Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

application/json

default

### Unexpected Internal Server Error An unexpected internal error occurred. We apologize for the inconvenience!

application/json

post

HTTPcURLJavaScriptPython

POST /gateways/{apigatewayId}/routes HTTP/1.1
Host: apigateway.de-txl.ionos.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 308

{
  "metadata": {},
  "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
      }
    ],
    "cache": {
      "enable": true,
      "httpMethods": [
        "GET"
      ],
      "httpCodes": [
        200
      ]
    }
  }
}

{
  "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": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "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
      }
    ],
    "cache": {
      "enable": true,
      "httpMethods": [
        "GET"
      ],
      "httpCodes": [
        200
      ]
    }
  }
}

Retrieve Route

get

Returns the Route by ID.

Authorizations

Path parameters

apigatewayIdstring · uuidRequired

The ID (UUID) of the Gateway.

Example: 0620c174-dd3c-5eb4-87c8-e2b516553a00

routeIdstring · uuidRequired

The ID (UUID) of the Route.

Example: 50982018-bb17-5cb9-bcd4-97f8bbc7dc23

Responses

200

Getting Route was successful.

application/json

400

### Bad Request The request send to the API was malformed.

application/json

401

### Unauthorized The request is missing authorization information or the authorization information provided are expired.

application/json

403

### Not Allowed The user issuing the request does not have the needed permissions.

application/json

404

### Not Found The resource that was requested could not be found.

application/json

429

### Too Many Requests The user has sent too many requests in a given amount of time.

application/json

500

### Internal Server Error An internal error occurred. We apologize for the inconvenience!

application/json

503

### Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

application/json

default

### Unexpected Internal Server Error An unexpected internal error occurred. We apologize for the inconvenience!

application/json

get

HTTPcURLJavaScriptPython

GET /gateways/{apigatewayId}/routes/{routeId} HTTP/1.1
Host: apigateway.de-txl.ionos.com
Authorization: Bearer JWT
Accept: */*

{
  "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": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "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
      }
    ],
    "cache": {
      "enable": true,
      "httpMethods": [
        "GET"
      ],
      "httpCodes": [
        200
      ]
    }
  }
}

Ensure Route

put

Ensures that the Route with the provided ID is created or modified. The full Route needs to be provided to ensure (either update or create) the Route. Non present data will only be filled with defaults or left empty, but not take previous values into consideration.

Authorizations

Path parameters

apigatewayIdstring · uuidRequired

The ID (UUID) of the Gateway.

Example: 0620c174-dd3c-5eb4-87c8-e2b516553a00

routeIdstring · uuidRequired

The ID (UUID) of the Route.

Example: 50982018-bb17-5cb9-bcd4-97f8bbc7dc23

Body

idstring · uuidRequired

The ID (UUID) of the Route.

Example: 50982018-bb17-5cb9-bcd4-97f8bbc7dc23

metadataanyOptional

Metadata

Responses

200

Route successfully updated.

application/json

201

Route successfully ensured.

application/json

400

### Bad Request The request send to the API was malformed.

application/json

401

### Unauthorized The request is missing authorization information or the authorization information provided are expired.

application/json

403

### Not Allowed The user issuing the request does not have the needed permissions.

application/json

404

### Not Found The resource that was requested could not be found.

application/json

409

### Conflict The UUID is already taken by another party, follow the guides to generate UUIDs uniquely.

application/json

415

### Unsupported Media Type The request has an unsupported media type.

application/json

422

### Unprocessable Entity The request was well-formed but was unable to be followed due to semantic errors.

application/json

429

### Too Many Requests The user has sent too many requests in a given amount of time.

application/json

500

### Internal Server Error An internal error occurred. We apologize for the inconvenience!

application/json

503

### Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

application/json

default

### Unexpected Internal Server Error An unexpected internal error occurred. We apologize for the inconvenience!

application/json

put

HTTPcURLJavaScriptPython

PUT /gateways/{apigatewayId}/routes/{routeId} HTTP/1.1
Host: apigateway.de-txl.ionos.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 352

{
  "id": "50982018-bb17-5cb9-bcd4-97f8bbc7dc23",
  "metadata": {},
  "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
      }
    ],
    "cache": {
      "enable": true,
      "httpMethods": [
        "GET"
      ],
      "httpCodes": [
        200
      ]
    }
  }
}

{
  "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": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "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
      }
    ],
    "cache": {
      "enable": true,
      "httpMethods": [
        "GET"
      ],
      "httpCodes": [
        200
      ]
    }
  }
}

Delete Route

delete

Deletes the specified Route.

Authorizations

Path parameters

apigatewayIdstring · uuidRequired

The ID (UUID) of the Gateway.

Example: 0620c174-dd3c-5eb4-87c8-e2b516553a00

routeIdstring · uuidRequired

The ID (UUID) of the Route.

Example: 50982018-bb17-5cb9-bcd4-97f8bbc7dc23

Responses

202

Deleting Route was successful.

400

### Bad Request The request send to the API was malformed.

application/json

401

### Unauthorized The request is missing authorization information or the authorization information provided are expired.

application/json

403

### Not Allowed The user issuing the request does not have the needed permissions.

application/json

404

### Not Found The resource that was requested could not be found.

application/json

429

### Too Many Requests The user has sent too many requests in a given amount of time.

application/json

500

### Internal Server Error An internal error occurred. We apologize for the inconvenience!

application/json

503

### Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

application/json

default

### Unexpected Internal Server Error An unexpected internal error occurred. We apologize for the inconvenience!

application/json

delete

HTTPcURLJavaScriptPython

DELETE /gateways/{apigatewayId}/routes/{routeId} HTTP/1.1
Host: apigateway.de-txl.ionos.com
Authorization: Bearer JWT
Accept: */*

No content