Managing IP addresses

Addresses live in prefixes, and prefixes belong to public virtual networks, so every IPv4 address call starts from the same path: /v1/networking/spn/{spnId}/prefixes/v4/{prefixId}, the network's id followed by the prefix's.

Find a prefix and its free addresses

Get virtual network lists the network's ipv4ChildPrefixes and ipv6ChildPrefixes, each with its id, datacenter, network, gateway, and how many addresses are used and free. Get IPv4 prefix then returns every address in one prefix:

curl --request GET \
  --url https://api.serverside.com/v1/networking/spn/{spnId}/prefixes/v4/{prefixId} \
  --header 'X-API-KEY: <api-key>'

Its data holds the prefix's network and gateway, the free addresses as a list in availableAddresses, and one entry per address under addresses. Each address has a state of FREE, RESERVED, GATEWAY or ASSIGNED, its rDNS name, the services it is assigned to and its id.

Reserve an address

Reserve IPv4 address holds an address back from the free pool without giving it to a server. Name the one you want as requestedAddress, or send an empty object to take any free address. The call answers 204; the prefix listing shows the address as RESERVED.

curl --request POST \
  --url https://api.serverside.com/v1/networking/spn/{spnId}/prefixes/v4/{prefixId}/reserve/addresses \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestedAddress": "198.51.100.27"
}
'

Reserving and assigning are two different uses of an address, not two steps. Assigning a reserved address is refused with 409 IP_ADDRESS_IN_USE; release it first.

Assign an address to a server

Assign IPv4 address to service binds an address to one of the server's segments. It takes the serviceId, the segmentId (listed by Get network capabilities) and, optionally, the requestedAddress:

curl --request POST \
  --url https://api.serverside.com/v1/networking/spn/{spnId}/prefixes/v4/{prefixId}/addresses/assign/service \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceId": "<service-id>",
  "segmentId": "<segment-id>",
  "requestedAddress": "198.51.100.26"
}
'

The answer is 201 Created with the ipAddressEntityId of the address and the spnAssignmentId it rides on.

A server's public addresses are not handed out over DHCP. The installer writes the addresses assigned before a deployment into the operating system as static configuration, and an address assigned afterwards has to be added by hand, with the prefix length and gateway from Get IPv4 prefix.

Release an address

Release IPv4 address returns an address to the pool and answers 204. The address goes in the path:

curl --request DELETE \
  --url https://api.serverside.com/v1/networking/spn/{spnId}/prefixes/v4/{prefixId}/addresses/198.51.100.26/release \
  --header 'X-API-KEY: <api-key>'

Errors

Reserving, assigning and releasing answer these:

Set reverse DNS

Set reverse DNS writes the PTR record for an IPv4 address. The API checks the name before it accepts it, so create the forward record first:

1. The name must be a fully qualified domain name. A trailing dot is allowed and dropped, and the name is stored in lower case.
2. The name must have an A record, and one of its A records must be this address.

curl --request POST \
  --url https://api.serverside.com/v1/networking/spn/{spnId}/prefixes/v4/{prefixId}/addresses/198.51.100.26/rdns \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "record": "mail.example.com"
}
'

Delete reverse DNS removes the record. The API has reverse DNS endpoints for IPv4 only.

IPv6

IPv6 prefixes work the same way with four calls under /prefixes/v6/{prefixId}: get the prefix, reserve an address, assign one to a server and release it.

Add address space with an IP block

When a prefix runs out, an IP block adds another to a network of your organization. List IP block plans shows the sizes on offer with their price per billing cycle and stock per datacenter; pass datacenterId to see one location. On a term, the block is an ipblock item of Create order, added once the order's invoice is paid (Billing). On hourly billing, Create IP block adds it in one request, which needs the organization's billing.usage_based entitlement and answers 422 USAGE_BILLING_DISABLED without it:

curl --request POST \
  --url https://api.serverside.com/v1/networking/ip-blocks \
  --header 'X-API-KEY: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offeringId": "<block-plan-id>",
  "datacenterId": "<datacenter-id>",
  "publicNetworkId": "<spn-id>"
}
'

The response returns the new prefixId and the subscriptionId it is billed under, hourly; a block that could not be allocated is refused with 409 PROVISIONING_FAILED. Delete IP block cancels the block's subscription, and a block with none of its addresses assigned is released at once. A block that came with a server is billed on the server's subscription, so deleting it is refused with 422 BUNDLED_ITEM_CANCELLATION_BLOCKED; it is released when the server is cancelled.