Designing the occupancy format

Occupancy looks trivial until you try to express it. Two adults and a nine-year-old in one room, plus one adult and two children in another, is a nested structure — and nested structures in query strings get ugly fast.

Most APIs solve this with repeated indexed parameters:

rooms[0][adults]=2&rooms[0][children][0]=9&rooms[1][adults]=1&…

It works. It is also unreadable, awkward to log, painful to cache on, and inconsistent between request and response.

One string instead

From version 0.10.x ApiXV expresses the whole thing as a single value. Rooms are separated by a pipe, guests within a room by a dash:

A-A-C9|A-C7-C4

Two rooms. The first has two adults and a child aged nine. The second has one adult and children aged seven and four.

The rules are short enough to hold in your head:

• A is an adult, C is a child
• A number after C is the child's age
• A number after A is the adult's age, and is optional
• Case does not matter — a29-a33-c14 parses identically

What it buys you

• The same format in both directions. Requests and responses use one representation, so there is no translation layer in your code.
• Readable logs. A-A-C9 in a log line tells you what was asked for without reconstructing it from six parameters.
• Trivial cache keys. The occupancy is already a string.
• Cheap validation. A regex catches malformed input before it reaches the network.

The limits

The format does not remove the underlying constraints, which are supplier realities rather than API choices:

• Maximum 4 rooms per request
• Maximum 6 adults per room
• Maximum 5 children per room

Ages matter more than you would expect. Child pricing thresholds vary by property, and a child of eleven is frequently priced as an adult. Sending C11 rather than a generic "child" is what lets the correct rate come back the first time.