Room status API documentation

[johnjohndoe]

Current state

After quite some searching, I was able to find the following pieces related to the room status API:

• https://api.fosdem.org
• https://github.com/FOSDEM/infrastructure/blob/master/ansible/playbooks/roles/json_exporter/files/config.yml
• https://github.com/FOSDEM/infrastructure/pull/133/files
• https://github.com/FOSDEM/infrastructure/blob/master/ansible/playbooks/roles/video-control-server/files/room_status.php

Request for docs

Can we please have a public documentation which targets the following groups:

1. Read only clients which want to consume the API response (e.g. mobile apps)
   • JSON structure
   • mandatory/optional properties and their meaning
   • response when FOSDEM is not running
2. Read/write clients which update the room state
3. Developers which want to contribute to the implementation code
4. Server administrator which want to run the feature

Related

Is there a staging environment which provides sample JSON responses at times when FOSDEM is not taking place?

Acknowledgement

I am personally interested in 1. because I am maintaining the FOSDEM Schedule app.

---

fyi @johanvdw, @SuperQ

[johanvdw]

I'm not too happy with the current status of the room full api. I think it should be recreated as an extension of pretalx which should be fairly simple.

Here is what I would propose for app developers.
An endpoint: pretalx.fosdem.org/fosdem-2025/p/roomstatus/list
This should return a list

• roomslug: janson
  roomname: Janson
  state: 0/1
  where 0: room is empty

We can rewrite calls going to the old /roomstatus/v1/listrooms to the current edition.
I'm a bit in doubt if we should keep it identical as it was before, or if we can make some changes to the endpoint, such as dropping 'id' and making state an integer instead of a string.

Given that the other endpoints are internal for us, I don't think we should keep compatibility.

Removing/registering rooms would no longer be necessary (as this is already in pretalx). The only other endpoint should be updateroom , which should be called from the video api. We can use a pretalx token for authentication here.

I'd propose:
post to pretalx.fosdem.org/fosdem-2025/p/roomstatus/<room_slug>
state=0/1

Apart from that would be nice to have a nice history view at some point of the room api, it would help in figuring out which devrooms need bigger rooms. The database design should take that into account (currently we keep a log of all changes).

For completeness: the repository and its deploy are currently in our internal git repository. I'll upload the repo to github as well.

[krokodilerian]

@johanvdw i'm fine with any api that I can squash in a single request. This state=1 to the URL looks nice, let me know how I can test it and I'll update the video-control to use it.

(also, if you have an endpoint to dump all room slugs, that'd be sooo nice...)

[johnjohndoe]

It might be a good idea to include GUIDs in the response to ensure room names never clash:

[
    {
        "guid": "ba692ba3-421b-5371-8309-60acc34a3c05",
        "name": "Room A",
        "state": 0
    },
    {
        "guid": "62251a07-13e4-5a72-bb3c-8528416ee0f2",
        "name": "Room B",
        "state": 1
    },
    {
        "guid": "10e6a40c-3b85-4df0-9731-af511d818fad",
        "name": "Room C",
        "state": 2
    },
]

The state value can be left open for extension, e.g. 0 -> empty, 1 -> full, 2 -> too full

[johanvdw]

So I had a second thought about this. Perhaps we are diving too deeply into technical details, and we should first take a step back to what we want to achieve:

• show room status in apps
• get an idea of room popularity after the event

Both don't really work well if the status is not updated regularly (or never at all). I think we also need a state 'unknown'. At least that is what we should put state at when a room changes track and at night.

I think ideally, someone would update (or confirm) the room status during each talk. If that has not happened for eg one hour, perhaps we should no longer use the old state.

For now I've let the person in charge of video of a room do that update. I'm still a fan of that solution. Devroom managers can find the link in their pretalx, but can also assign a volunteer to do it without having to share their details.

[keunes]

I think ideally, someone would update (or confirm) the room status during each talk
For now I've let the person in charge of video of a room do that update

In the past there were also suggestions for herralders doing this – that might be something for later when we have a decision on the volunteer system.

If that has not happened for eg one hour, perhaps we should no longer use the old state.

Yes, or maybe even reset 5 minutes after the start of a talk (if status hasn't been changed/confirmed in the past five minutes)? On the other hand, that may mean whoever gets to update the status, has to do that very often.