REST API

[gazwald]

API

Initial Web interface/API specification

Endpoints

• Each endpoint, unless otherwise stated, to return either plain, HTML, or JSON content depending on the request.
• Endpoints are listed in the order they'll be prioritised

Servers

Endpoint	Methods	Description	Plain	JSON	HTML
/servers	GET	return a list of servers (address:port only)	yes	yes	yes
/servers?game=<game>	GET	return a list of servers (address:port only) for <game> running any mod	yes	yes	yes
/servers?game=<game>?mod=<mod>	GET	return list of servers (address:port only) for <game> running <mod>	yes	yes	yes
/servers/<game>	GET	return a list of servers (address:port only) for <game> running any mod	yes	yes	yes
/servers/<game>/<mod>	GET	return list of servers (address:port only) for <game> running <mod>	yes	yes	yes
/server/<server id>	GET	return all information for <server id>	no	yes	no

Games

Endpoint	Methods	Description	Plain	JSON	HTML
/games	GET	return list of all games we currently have active servers for	no	yes	no

Players

Endpoint	Methods	Description	Plain	JSON	HTML
/players/<server id>	GET	return list of all players in <server id> if server is active	no	yes	no
/players/<game>	GET	return list of all players in all active <game> servers	no	yes	no

Notes

JSON Filtering

• At a later date any endpoint that supports a JSON response will be updated to allow a POST request containing filtering information.

Fast API

• Can handle requests with body + path + query parameters
• Can handle additional responses, e.g.: html, plain, and json responses.

[darkshade9]

Regarding /server/<server id>, is this ID generated (integer or GUID) or is it keyed off of the IP:PORT combo to define a unique server id/instance?

Thoughts on having GET requests be parameterized, a la /servers?game=quake2&mod=action as the filter mechanism?

[gazwald]

Regarding /server/<server id>, is this ID generated (integer or GUID) or is it keyed off of the IP:PORT combo to define a unique server id/instance?

Server ID is currently the ip:port combination.

Although that brings up a good point about how that ID will look with URL encoding.

Thoughts on having GET requests be parameterized, a la /servers?game=quake2&mod=action as the filter mechanism?

Had planned for querystring to pop up at some point for additional filtering. I think it's probably cleaner to support it for all filtering including game and mod like your example - makes bookmarking easier. Then have the addition of the hierarchical method /servers/<game>/<mod> for flexibility later on.

I'll update the initial issue comment later with some more fleshed out ideas.

[darkshade9]

I'm thinking about the end user utilizing the API, as a broad, sweeping "get me all the servers and their info" or a focused "I only care about this server" type queries. Q2Pro currently runs this query and parses the JSON output to format the server list specifically for the action mod: pushmenu servers "http://q2servers.com/?g=action&raw=1", I imagine this would be the majority of use?

[gazwald]

http://q2servers.com/?g=action&raw=1 is text/plain not JSON. I initially started working on this master because they didn't output JSON 😂 ... which seems pretty minor now after all the other work.

I've updated the initial issue with added detail about requests, query strings, and responses.

You're right that the majority of use would be just "get me all the servers" . Main reason for having things more nuanced would be for web browser access or if someone feels like writing a mobile app for it in the future. Not necessary for the bulk of initial traffic though.