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, which firewall assignments use.

Reserve an address

Reserve IPv4 address holds an address back from the free pool. 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.26"
}
'

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. 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>'

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. List IP block plans shows the sizes on offer with their price per billing cycle and stock per datacenter; pass datacenter_id to see one location. Create IP block adds the block to a public network:

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. Delete IP block returns the block.