PieFed API & mobile app dev

• https://piefed.social/api/alpha/topic/list
• https://piefed.social/api/alpha/feed/list - This one has two boolean parameters: mine_only (only return feeds the current user created) and exclude_communities (reduce result size)

Also /api/alpha/post/list now has a topic_id and a feed_id parameter, to get posts in those topics and feeds.

No PUT, POST, etc endpoints yet, only GET.

There is a NEW endpoint /api/alpha/post/replies. In the past comments/list was used to get lists of comments for a variety of situations, making it hard to debug, have many many parameters and it's response overly verbose. That endpoint will remain there, unchanged, for compatibility reasons. You can continue using it if this new endpoint is not to your liking.

The new endpoint post/replies is only for getting replies to a post and as such the response is not a flat list of comments, it is a nested hierarchy thing which mirrors the way the replies are displayed in the UI. It's parameters are the same as comments/list, as much as possible, including max_depth, limit, post_id, parent_id.

Let's take this post as an example: https://piefed.social/post/1076697?sort=hot#replies. I chose that one because the conversation has a nice hierarchy to it and yet there are only 25 replies so it's something we can get our arms around.

The comment structure is the same as before except I added a 'replies' attribute on the end which is a list of comments, which in turn have 'replies' on them. Only the top-level replies have 'post' and 'community' as this data would be the same for all child replies and is redundant.

To get all the replies to a post:

https://piefed.social/api/alpha/post/replies?post_id=1076697&sort=Hot

To paginate the replies, while getting full unbroken reply trees, specify a page size using 'limit'

https://piefed.social/api/alpha/post/replies?post_id=1076697&sort=Hot&limit=3

The above limit is intentionally small so you can see that the result includes the entire first branch. IRL you will want 20 or 50. NB the result includes a 'next_page' value:

This is different to the pagination on the rest of the API - it is the ID of the first comment on the next page, rather than a page number. You use it the same tho - you can get the next page of results by doing

https://piefed.social/api/alpha/post/replies?post_id=1076697&sort=Hot&limit=3&page=7228615

The problem with page numbers is that people can create replies in the time between when you got the first page and when you got the second (or later) pages, so replies can end up being in two pages of results. By basing the pagination on the ID of the reply we avoid this.

You can omit post_id and instead provide parent_id to get a sub-branch deep in the discussion. The max_depth filter will be applied relative from parent_id, not the root.

As part of our ongoing effort to make the piefed api self-documenting and validate the input and output, there have been a couple tweaks to the api. I realized that I should probably document them here since not everybody is keeping tabs on every codeberg PR that comes through the repo.

• canAuthUserModerate has been renamed to can_auth_user_moderate in the CommentView schema. This transitioning from camelCase to snake_case will be a theme as I work my way through the endpoints, this is just the first that I ran across.
• The title field in the PersonView schema will now be equal to the user_name instead of null if the user never set a display name. The way this was handled was a bit inconsistent between local and remote users, but now all users should have this behave the same way.
• All of the timestamps in the InstanceWithoutFederationState schema have been standardized to the same format. Previously, these were in the standard iso format, but didn't have the Z at the end.
• The Site schema can now return the site sidebar in html and markdown (if both formats are present). The sidebar field will continue to be html, while the new sidebar_md field will provide the markdown rendition of the sidebar. In the past, the sidebar was only in html, so the markdown version will only become available after an admin updates their instance's sidebar to use markdown instead of html.

That's all the changes that are live up to this point. I will continue to make posts in this community as changes are made to try to keep you all in the loop.

While we are talking about the future, other plans for the future are to have a dedicated development instance for testing bleeding edge code while keeping piefed.social on a more stable branch. In the meantime, feel free to peruse my instance's swagger ui (json version), which is up to date with the api changes as I am working on them (community endpoints are next).

Hello! I am getting 400 errors when hitting the piefed.social. Hitting other piefed instances appear to work.

The exact error I get is:

{"code":400,"message":"{'my_user': {'instance_blocks': {0: {'site': ['Missing data for required field.']}}}}","status":"Bad Request"}

As an example I get this error when I make a GET request to https://piefed.social/api/alpha/site.

Note that I am making with request without an Authorization header.

Update

It seems that only alpha/site endpoint is broken. I can GET https://piefed.social/api/alpha/federated_instances just fine.

POST /community/moderate/ban was using expiredAt while the rest of the API is in snake_case. Also some of the response was not in snake case either, so I tided that up.

PUT /community/moderate/unban is also affected. (why is it a PUT??)

GET /community/moderate/bans now uses snake case.

We're cooking up an automatically-updated swagger / openapi solution right now, please bear with us.

GET /api/alpha/user was already returning default_sort_type but it now also returns default_comment_sort_type (for sorting comments, not posts). It was also returning show_nsfw and it now also returns show_nsfl.

You can also PUT those values to /api/alpha/user/save_user_settings to... guess what, save their settings.

Although PieFed has these default sorts it's up to the API user to use them when GETing /post/list and /comment/list as those endpoints will default to 'Hot' if there is no sort parameter.

At the bottom of https://codeberg.org/rimu/pyfedi/src/branch/main/app/api/alpha/routes.py#L869 you can see a bunch of endpoints that are not implemented. There are others we could do with too, like endpoints for feeds and topics...

Please highlight the highest priority things that you feel are missing at the moment, in the comments.

This issue is in the work queue for v1.1 and is one of the only substantial pieces of work remaining before we release that version. So I'm keen that I or someone to get started on this very soon.

It could be quite disruptive to apps that already use this endpoint so I thought I'd ask people how they want this to go. I'm thinking just make a whole new endpoint, maybe /api/v1/comment/list...

• filtered is true if one of the user's keyword filters should hide this post from them.
• blurred is true if the post is nsfw, nsfl, from a bot or contains a spoiler and they indicated they don't want nsfw, bot posts, etc.