As part of our ongoing effort to make our api self-documenting and validating our api input/output, we have been working through the api endpoints one at a time to make things a bit more consistent and logical. I just finished doing this for our existing /community endpoints and thought I would share the changelog here for awareness and feedback.

As of right now, these changes are only live on my instance and on our new, dedicated testing instance, crust.piefed.social. The self-documenting swagger for 1.2 (a WIP) can be found here.

1.2 Community Endpoints Changelog

  • PUT /community
    • input parameter community_id properly documented (was previously erroneously documented as id)
  • GET /community/list
    • made next_page nullable if there is no next page
    • this change was backported to 1.1 already
  • GET /community/moderate/bans
    • banned_by replaces bannedBy - transitioning everything to snake case
    • banned_user replaces bannedUser - transitioning everything to snake case
    • expired_at replaces expiredAt - transitioning everything to snake case
    • expired_at value of null indicates a permanent ban
    • expired_at only returned if ban has expired
    • expires_at field added, only returned if ban is still in effect
    • expires_at value of null indicates permanent ban
  • PUT /community/moderate/unban
    • same field name changes as above (snake_case instead of camelCase)
    • expired_at is now set equal to current time if ban was found (indicating that it was just set to expired) and returned in standard timestamp format found elsewhere in the api (2025-06-07T02:29:07.980084Z)
  • POST /community/moderate/ban
    • Input:
      • expires_at replaces expiredAt/expired_at for input
      • expires_at uses standard timestamp format (2025-06-07T02:29:07.980084Z)
      • expires_at is optional
      • expires_at is checked to make sure it is in the future, raises an exception if it is not
      • permanent is new optional boolean field, supercedes expires_at if true
      • If expires_at is not provided and permanent is either false or not provided, then the ban is set to expire in one year
    • Output:
      • same field name changes as above (snake_case instead of camelCase)
      • expires_at value of null indicates permanent ban
      • standardize timestamp format of expires_at
      • only returns expires_at because it is a time in the future (does not return expired_at)
  • freamon@preferred.socialEnglish
    2·
    3 months ago

    The case inconsistencies with the moderate endpoints come from them being inspired by Mbin rather than Lemmy.

    For max consistency, it might be an idea to kill moderate/unban and just send a Boolean tomoderate/ban (e.g. with “banned”: true/false)

    • wjs018@piefed.wjs018.xyzOPEnglish
      1·
      3 months ago

      I actually kind of like it being a separate endpoint, so I don’t mind that. One thing I thought about changing though, that I opted not to, was to make both /ban and /unban the same request method. Right now /ban is a post while /unban is a put. I feel like they should both be the same. However, this felt like more of a bigger change than some field name tweaking, so I held off.