[RFC] API

[galaxyAbstractor]

Abstract
A sort of API that enables users to interact with a phpBB forum from within other applications, such as for example a desktop application.

Further Description
I would like to see some kind of API in place to be able to interact with a forum in more ways than accessing it from the forum itself. It should allow developers to easily create an application, either dedicated to doing phpBB stuff for example a desktop client or a mobile client (what I understand from a friend of mine, this has already been discussed to a no but I do not know the exact details of it, but it's just an example I'm using) or a regular application that integrates phpBB in a way, maybe for integrated bug reporting in a game?

Suggested Usecases

• Dedicated desktop applications
• Mobile applications?
• A better integrated forum than a browser frame in, say, a game. It could be used for in-game discussion, easier bug-reporting (bug report could automatically be posted to correct forum upon user choosing to submit one)
• Integration with blogsystems/CMSes, an example if a news post is posted in the CMS, it could be automatically posted to a news forum as well
• More

How
Implement an API of some kind, JSON seems to be a reasonable choice seeing it being pretty common in other APIs and fairly easy to work with, but other, more suitable, if any, solutions could also work? It should be easy to use and understand. It should be able to be enabled/disabled trough the ACP in case the administrator runs ads on the board and don't want to lose impressions or for other reasons. It should be accessible to the users so the users easily can use a 3rd part application (much like the twitter API does it), maybe with some keypair solution instead of using passwords that might be insecure? Of course would board permissions still apply to the data returned by the API and what can be run. Also an ability to limit the API usage to certain groups may be a feature, like if the admin wants to implement point 3 of the suggested usecases but doesn't want users to use the API. This could be done by only accepting keypairs of users in the right groups (this could contribute to the "ad" issue I've heard of when dealing with APIs, users could pay/donate an amount to be able to access the API).

Suggested start of implementation
It would be nice to have some basic implementation with most basic features implemented, like ability to see posts and forums and post new topics/replies. Later more features could be added, like UCP, MCP and even ACP.

Sorry if I missed anything/I'm not clear on something, it's kinda late and I'm a bit tired

[A_Jelly_Doughnut]

An API would be lovely. I'd like to see it start with an API that other PHP scripts can use with some relative degree of ease (include a file, instantiate a class or two, then start adding users). An AJAX API could be a service layer that depends on the PHP level API.

[callumacrae]

+1 to most of the idea, but I don't think stuff like *CP should be added.

[naderman]

This sounds like a great idea and could benefit phpBB greatly. I agree with Josh that we should probably build a PHP API, and then expose it through a REST interface potentially using JSON for the data, which could be consumed by clients like you explained in your RFC.

[callumacrae]

This sounds like a great idea and could benefit phpBB greatly. I agree with Josh that we should probably build a PHP API, and then expose it through a REST interface potentially using JSON for the data, which could be consumed by clients like you explained in your RFC.

I see potential for the use of PATH_INFO here:

Code: Select all

DELETE /phpBB/api.php/json/post/2

And in a hook file somewhere:

Code: Select all

$api->delete('post/:postid', function ($params) {
    delete_post($params['postid']);
});

[galaxyAbstractor]

What about using OAuth to authorize users in 3rd party apps? That way the user wouldn't need to give away their passwords but can give a temporal/limited token. This is much like the Twitter API does.

[naderman]

Seems like a good way to do this.

[_hsr]

This is almost what I meant by a JavaScript API, I'd love to work on an SDK for PHP and JS, once this is implemented.

Auth can be done via tokens and secrets, in the ACP, an admin can allow/deny an application requesting API access. Just like any other API service, the user needs to be auth'ed only once into the system. JSON should be the primary method, but including XML as an option wouldn't be so hard, a JSON to XML parse should do fine.

[galaxyAbstractor]

This is almost what I meant by a JavaScript API, I'd love to work on an SDK for PHP and JS, once this is implemented.

Auth can be done via tokens and secrets, in the ACP, an admin can allow/deny an application requesting API access. Just like any other API service, the user needs to be auth'ed only once into the system. JSON should be the primary method, but including XML as an option wouldn't be so hard, a JSON to XML parse should do fine.

Though if the app needs to be allowed on each phpBB board, it would be quite hard for app developers to create some sort of applications, like a mobile app to browse all phpBB boards or something of the likes because an app developer can't possible register with all phpBB boards. But if it's somewhat automatic perhaps, like the first time the app tries to access an API on a board, it would notify the admin to approve it once (and return an error message to the user of the app that the admin yet has to approve it)?

[Jocelyn79]

What about an API like IPBWI, that works with IPB forums?
It contains many powerful ready-to-use functions, there's no need to bother with including many phpbb source files, declaring variables or constants, sending queries to the database...
I used an Invision forum until it became a commercial-only solution, together with IPBSDK (it has now been replaced with IPBWI).
I could then create new posts or new topics with only 2 or 3 lines of code.

Currently, if you want to do the same thing with phpbb, you need to use many lines of code, such as what is shown here, you need to understand exactly how to use functions such as generate_text_for_display() or generate_text_for_storage().

A well-thought API could hide all this complexity, enabling many users to easily program whatever they feel like.