Housing API Draft

[ixnoahlive]

Edit: This thread was originally meant for the forums, hence the sassyness. Sadly, the post can't be made due to some complicated glitchyness with my account status preventing me from posting for a bit. I reposted it here with no second look but that's all clarified down below. The rude parts are withdrawn and I don't stand by them anymore! ❤️

Housing API Draft

Hi all, I come at you again with a proper proposal for a Housing API! I understand because of Housing being a very old gameplay there may be tech debt in adding these endpoints, but some of these are just stupid for not existing.

Cookies

• There is a cookie leaderboard in the lobby, but the Housing Leaderboards are not in the Leaderboard API for some reason. If LOBBY FISHING got an API entry while the 3rd biggest gamemode has none then that's a little pathetic.
• Amount of Cookies a player has should be in their housingMeta. Given Cookies is public, why not earned cookies?

House Metadata

This is what I'll be referring to as HouseMeta in this thread. This is the data you can access about a house.

{
    "owner": { "displayname": "ixNoah", "uuid": "xxxx-xxxx" },

    "name": "&aMy Awesome &bHome",
    "map_id":"xxxx-xxxx"

    "guests": 150,
    "maxGuests": 250,

    "cookies": 1258,
    "totalCookies": 1259, // Pretty sure this is tracked for my2023, no reason not to add.

    "server": "m69gg", // undefined or a string
}

House Browser

Spicy custom stuff coming up! All bullet points are parameters you can fill in.

/resources/housing/browser

• channel

  • The channel tag to browse, defaults to GUESTS, but can be things like tags as RP (roleplay) or M (minigame).

• player

  • UUID or Username, returns that player's houses.

• house

  • Search via the map_id of a house.

• Returns HouseMeta[]

Advanced House Data

Okay, a little more spicy. This should probably be an option in House Settings to expose, perhaps with the new API system it could be locked so you can whitelist certain API keys to access data? Who knows!?

Context: Stats are Housing's variable system.

• /resources/housing/stats
  • house
    • The map_id of the house
  • player
    • The UUID or Username of the player you want to view stats of.
  • global
    • Boolean, if true it will not search for a player but instead the globally stored stats.
  • team
    • The name of a team to view the team stats of. I doubt anyone will use this but we might aswell include it.

Returns key-value object of that player's stats like below.

{
    "displayname": "ixNoah",
    "uuid": "xxxx-xxxx",
    "stats": {
        "awesome": 1,
        "kills": 69,
        "deaths": 48175
    }
}

Conclusion

Housing is the 3rd biggest gamemode, but in terms of API it's severely lacking. I hope this post can inspire the devs to take a look into this since it would be a huge upgrade if added.

If the admins are wanting to work on this but want to sit down with developers, fear not, because the HousingDevs group consists of the top Housing modders (including creators of sites & mods like HousingEditor!) and we'd love to sit down and have a chat!

[ConnorLinfoot]

There have been internal designs for a basic Housing API for a while, but with our current overall roadmap, there is no ETA for when, or even if, anything will be released. The overall value is hard to determine, but looking at the only other bespoke game endpoints (skyblock) and the changes required, it's going to be very low in comparison to the work involved.

In general, I think it's a little rude to say it's "stupid" for the endpoints to not exist, or to say it's "pathetic" that a leaderboard isn't included (which is more than likely a bug). This for sure isn't the correct way to go about attempting to have changes implemented to the API. I would also recommend taking a look at existing endpoints, as your current proposal goes against our current structure, especially in regards to putting the endpoints under resources while offering dynamic content.

[ixnoahlive]

@ConnorLinfoot
First of, apologies for the rudeness! This was initially a forum thread but I can't access those atm and thus I copy-pasted the BB code and converted it to markdown with slight changes without a second look. This is also why the endpoints were somewhat slobby (I thought resources was for any direct ingame assets like with Auction House) and I didn't really follow any style guides as forum suggestions tend to be a little less serious. Again, really sorry.

I understand the rest of your points, seems crystal. No comments or questions regarding that.

Thank you for fast reply!
Edit & PS: If you or other folks think it could be valuable, I can hold a little discussion with some of the folks at HousingDevs on what their needs are and rework the thread around that though I understand if you're a bit put off by the initial thread.

[ConnorLinfoot]

All good! Just a small heads up that the cookie leaderboards are now available on the relevant endpoint. But they are probably not the most useful since I don't believe there is currently any method to get the earned cookies for a specific player via the API, maybe one day if we can find the time to develop some Housing endpoint(s).

[ixnoahlive]

Hey! So a few features regarding Housing were added to the API this week! Are the way these are being used right now final? I'd be down to work on implementing them into the examples!