Proposed REST API

The REST API allows you to easily communicate with a phpBB board from your applications.

NOTE: This API is not part of phpBB in 3.0 and 3.1, it is just the definition which was agreed on, while the implementation was started as a Google Summer of Code Project.

= Making Requests = Requests are made using HTTP GET and POST depending on what you want to do.

Authentication
The phpBB REST API uses a key system for authentication so that users never have to release their passwords to third parties. For added security requests are hashed using a signing key. When authenticated for the first time, an auth key and a signing key is generated by the board and given to the client which asks the user to authenticate the client using the keys. From there on the request is hashed using the signing key and the hash is added to the request. This is to prevent someone hijacking the auth key. A serial is also added to the request to counter replay attacks which needs to be incremented for each request. phpBB uses hmac-sha256 for hashing.

$request = 'api/forums/2/topics'; // Request to make

$request_to_hash = $request. 'auth_key='. $auth_key. '&serial='. $serial; // This is what we want to hash

$hash = hash_hmac('sha256', $request_to_hash, $sign_key); // Hash it using the signing key

$request .= '&auth_key='. $auth_key. '&serial='. $serial. '&hash=' $hash; // Add auth data to the request. Note this will change soon

$request = $url. $request; // Add the URL of the API you want to access

= Endpoints =

Get Keys
/api/auth/generatekeys

This method returns 2 keys, one used as authentication key and one as the signing key. You should pass this in the URL where the user authenticates your application, check the Authenticating Keys section.

Response {

"status": int, "data":{ "auth_key": string, "sign_key": string }

}

Authenticating Keys
/api/auth/{auth_key}/{sign_key}

This is the method the user will authenticate your application. Note that this is a URL you should give to the user/open in a browser, not call yourself.

Verify Keys
/api/auth/verify

If you want to make sure the authentication key is valid, this can be used to check it. It's a good thing to check this after the user has authenticated your application to be sure about having a working key.

Response {

"status":int, "data":{ "valid":boolean, "usertype": string, "member"|"guest" }

}

List Forums
/api/forums/{forum_id}

This returns a list of all forums and their subforums using the given forum_id as parent. If you want to retrieve all forums, do not specify a forum_id. The returning array is recursive, having all subforums of a forum in the subforums index and so on.

Response {

"status":int, "data":[ {           "forum_id": int, "parent_id": int, "forum_name": string, "forum_desc": string, "forum_link": string, "forum_image": int, "forum_rules": string, "forum_rules_link": string, "forum_type": int, "forum_posts_approved": int, "forum_topics_approved": int, "forum_last_post_id": int, "forum_last_poster_id": int, "forum_last_post_subject": string, "forum_last_post_time": int, "forum_last_poster_name": string, "forum_last_poster_colour": string, "subforums":null|array }   ]

}

List Topics
/api/forums/{forum_id}/topics/{page}

Returns a list of topics in the given forum. If page is not defined, page 1 is returned. Currently returns as many topics as the boards 'topics per page' setting. Currently sorted by descending topic_id (todo: make it sort by last post instead).

Response {

"status": int, "data":[ {           "topic_id": int, "forum_id": int, "icon_id": int, "topic_title": string, "topic_poster": int, "topic_time": int, "topic_views": int, "topic_posts_approved": int, "topic_type": int, "topic_first_post_id": int, "topic_first_poster_name": string, "topic_first_poster_colour": string, "topic_last_post_id": int, "topic_last_poster_name": string, "topic_last_poster_colour": string, "topic_last_post_subject": string, "topic_last_post_time":int }   ] }

List Posts
/api/topic/{topic_id}/{page} Returns a list of posts in the given thread. If page is not defined, page 1 is returned. Currently returns as many posts as the boards 'posts per page' setting. Sorted by ascending post_id.

Response {

"status": int, "data":[ {           "post_id": int, "topic_id": int, "forum_id": int, "poster_id": int, "icon_id": int, "post_time": int, "post_username": string, // Empty if registered user, filled if guest poster "post_subject": string, "post_text": string }   ] }

Create New Topic & Reply To Topic
/api/post

To create new topics and posts, you would POST some json to this endpoint.

Step 1 $data = array(	'auth_key' => '',	'serial' => 0,

'username' => '', 'topic_type' => 0,

'forum_id' => 2, 'topic_id' => 0, 'icon_id' => 0,

'enable_bbcode' => true, 'enable_smilies' =>true, 'enable_urls' => true, 'enable_sig' => true,

'message' => '',

'topic_title' => '',

'notify' => false, );

To create a new topic, make sure to set topic_id to 0, to reply to a topic, put the topic id you are replying to as topic_id.

Step 2 Implode the array with '/' as glue

$imploded_request = implode('/', $data);

Step 3 Hash the imploded request with the signing key.

$hash = hash_hmac('sha256', $imploded_request, '');

Step 4 Put the hash and jsonencoded array in an array which you will POST to the endpoint.

$request['hash'] = $hash; $request['data'] = json_encode($data);

Response {

"status": int, "data":{ "post_id": int }

}

Notes This endpoint isn't fully done yet.

= Links =
 * [RFC]
 * [Pull Request]