Description of fields returned by Discourse API

dev
1

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!

1 Like
2

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:

image
image1098×734 46.1 KB

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}

3 Likes
3

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.

4

That is understandable. There is similar code though. It’s here: https://github.com/discourse/discourse/blob/master/app/models/post.rb#L145. 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.

3 Likes
5

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?

1 Like
6

I agree that these fields need to be documented. I’ll assign this topic to myself and make sure that it gets done.

3 Likes