EYeyevinn
ports

Reserve ports.

Changed on

Reserves ports for owner_id until ttl_secs after the last request or renewal. The call is idempotent per owner: an owner that already holds a reservation gets it back, renewed, with a 200 instead of a 201, and its existing ports are never moved. A count larger than it holds adds ports, preferring ones that continue the block it already has; equal or smaller changes nothing but the expiry, since ports are given back by deleting the reservation rather than by shrinking it. ports is an explicit list and callers must not assume it is contiguous.

post/api/ports/reservations

Request

  • The document declares no server URL.
  • Auth
    none declared

Request body

countinteger required

How many ports the owner wants to hold in total. Larger than it holds now adds ports; equal or smaller leaves them alone.

owner_idstring required

Stable name of the owner, such as a production or instance id. A repeat request under the same name renews and returns the existing reservation rather than allocating a second one.

ttl_secsinteger nullable

Lifetime in seconds. Defaults to the server's configured TTL.

Response

The owner's existing reservation, renewed

created_atstring required

When the reservation was first granted (RFC 3339, UTC).

expires_atstring required

When it lapses unless renewed (RFC 3339, UTC).

idstring uuid required

Reservation identifier, used to renew, release and assign.

owner_idstring required

The owner's stable name. One reservation per owner; asking again returns it.

portsinteger[] required

The ports held, ascending.

Changes