I am using the Discourse API to extract posts from a forum. I need help in understanding the meanings of the fields returned by the API. For example, post_type
field in each post
is a number. What are the valid values and what do they mean? Similarly, the id
under actions_summary
is a number. There are other fields such as reads
, score
, etc. which I am not clear about. Any pointers on where I can get this information. Thanks!
If you have the Data Explorer plugin installed on your site, you can get details about the number codes used by hovering over the entries:
For example, hovering over the posts
post_type
field shows the following values:
- regular: 1
- moderator action: 2
- small action: 3
- whisper: 4
Other than the Data Explorer, the only place I know of to find this information is in the Discourse code. For example, to find the meaning of each action_type
from the user_actions
table, enter UserAction.types
at the Rails console. That returns the following values:
{:like=>1, :was_liked=>2, :bookmark=>3, :new_topic=>4, :reply=>5, :response=>6, :mention=>7, :quote=>9, :edit=>11, :new_private_message=>12, :got_private_message=>13, :solved=>15, :assigned=>16}
Thanks @simon ! This is an interesting way to get this info. I did some digging based on your suggestions and found this piece of code for user_actions
, but could not find something similar for post_type
after considerable searching. I was hoping that every field returned by the API would be documented somewhere, at least for important fields that carry significant semantics.
That is understandable. There is similar code though. It’s here: discourse/app/models/post.rb at main · discourse/discourse · GitHub. The structure of the DIscourse database is very consistent. Hopefully this helps to make up for the lack of documentation.
I’m not sure that every field returned by the API will get documented, but documenting the various places where number codes are returned seems important. Example of this are:
Post.types
UserAction.types
Notification.types
NotificationLevels.all
UserOption.email_level_types
If we go ahead with this, I’m not sure what the best place would be for the documentation. Possibly at https://docs.discourse.org/, but it’s possible there will be technical issues with doing that.
Thanks @simon! Yes, listing the English names/one-line descriptions for numeric codes would be very useful. Is there someplace I can place a request for this?
I agree that these fields need to be documented. I’ll assign this topic to myself and make sure that it gets done.