<< Back to GForge REST API

Entity: Forum

GET

getChat

Get a reference to the chat thread for a given project. Creates the forum and thread if they do not yet exist.

Parameters (2)

Name Type Description
section string Section identifier. Currently only project is supported. Required
refId int Database ID of the project. Required

Return: \gforge\plugins\forum\models\api\ForumThreadBasic

The forum thread for this project's chat room.

Name Type Description
id int Unique database identifier for the forum
threadName string name for the thread
messageCount int number of messages under this thread
mostRecentDate \DateTime most recent post on the thread
isLocked string Y if the thread is locked,, N otherwise
isSticky string Y if the thread is sticky,, N otherwise
usersOnline array userBasic array, a chatroom users online list
forum \gforge\plugins\forum\models\api\ForumBasic Forum which the Thread belongs to (optional data)

getForum

Searches for forums matching criteria, or retrieves a specific forum by its database ID or mailman list name.

Parameters (10)

Name Type Description
id string The database ID or mailman list name of a specific forum to retrieve. When present, all other filter parameters are ignored.
rel string Comma-separated list of related data to include. Valid values: mostRecentMessage, isChat, threadParentCount.
sort_field string Field to sort search results by. Valid values: id, section, refId, forumName, isPublic, threadCount, messageCount, mostRecentDate, moderationLevel. Defaults to id.
sort_dir string Sort direction. Valid values: asc, desc. Defaults to asc.
page_num int Zero-based page index for paged results. Defaults to 0.
page_size int Number of results per page. Defaults to 20.
section string Filter: section of the forum (e.g. project, mailman).
refId int Filter: reference ID of the object the forum belongs to.
forumName string Filter: name of the forum.
isPublic bool Filter: whether the forum is public.
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\plugins\forum\models\api\ForumDetail|\gforge\plugins\forum\models\api\ForumDetail[]

getMostRecentMessage

Finds the most recent message within a given forum by forum ID.

Parameters (1)

Name Type Description
id int The database ID of the forum whose most recent message is to be retrieved. Required.

Return: \gforge\plugins\forum\models\api\ForumMessageBasic|null

getThreadparentcount

Get the count of messages in a thread that do not have a parent message (i.e. top-level messages).

Parameters (1)

Name Type Description
id int Route parameter — database ID of the ForumThread. Required

Return: array

Associative array with a count key containing the integer count.

POST

postForum

Create a new Forum

Parameters (4)

Name Type Description
section string Section of the forum. Required
refId int Reference Id of the forum. Required
forumName string Name of the forum. Required
isPublic bool Whether or not the forum is public. Required

Return: array

Example 1

The following curl command:


  curl -d section=tracker -d refId=999 -d forumName=test -d isPublic=true --user username:password http://gforge.api/forum

Creates this forum:


{ section="tracker", refId=999, forumName="test", isPublic=true }

postThread

Create or update a ForumThread. The forum is identified by the route parameter; pass id=0 (or omit it) to create a new thread, or pass an existing thread ID to update.

Parameters (5)

Name Type Description
forumId string Route parameter — database ID or email alias of the forum. Required
id int Route parameter — database ID of the thread to update, or 0 to create. Defaults to 0.
threadName string Name of the thread. Required when creating.
isSticky bool Whether the thread should be pinned to the top of the list.
isLocked bool Whether the thread should be locked against new replies.

Return: array

Associative array with a location key containing the API URL of the thread.

Example 1


  curl -d section=tracker -d refId=999 -d forumName=test -d isPublic=true --user username:password http://gforge.api/forum/:forumId/thread/:id

postUserOffline

Set the authenticated user as offline in the specified chat room, or in all chat rooms if threadId is not provided. If section and refId are supplied instead of threadId, the method resolves the appropriate thread automatically.

Parameters (3)

Name Type Description
threadId int The database ID of the ForumThread (chat room) to leave. Optional.
section string Section identifier used to resolve the thread when threadId is absent (e.g. project).
refId int Reference ID of the section object used to resolve the thread when threadId is absent.

Return: bool

Always returns true.

PUT

DELETE

deleteForum

Delete a forum

Parameters (1)

Name Type Description
id int Id of forum to be deleted. This field is set in the resource location (DELETE /api/forum/[id]) Required

Return: (none)

Example 1


  curl -X DELETE --user user:pass https://api.gforge.com/forum/1234

deleteThread

Delete a forum

Parameters (1)

Name Type Description
id int Id of forum to be deleted. This field is set in the resource location (DELETE /api/forum/[id]) Required

Return: (none)

Example 1


  curl -X DELETE --user user:pass https://api.gforge.com/forum/1234