PHPBB3-11595 - API

[galaxyAbstractor]

Ticket: https://tracker.phpbb.com/browse/PHPBB3-11595
PR: https://github.com/phpbb/phpbb/pull/3100
-----------

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

Current status
There are currently 2 pull requests:

• https://github.com/phpbb/phpbb/pull/1490
• https://github.com/phpbb/phpbb/pull/3100

The first one is the original pull request, but it was decided it would be closed and smaller pull requests would be opened for each part, as the original had gotten pretty massive.

What exists in the original PR
The original pull requests contains a custom authentication system for the API and endpoints for listing forums, threads and post as well as submitting new topics and creating replies. This PR is pretty outdated right now since I've continued the work on the auth system in the newer PR, and things in phpBB has changed meaning the various endpoints probably wont work without changes (although I don't think they have to be redone from scratch, just updated).

The new PR
The new PR only contains the authentication system. The auth system is built upon the auth system I originally created, but some extra features have been added and bugs fixed, as well as updating it to work with new route system etc.

What needs to be done
There have been discussions in IRC and in this thread to implement OAuth2 as the auth system. This probably needs to be the next thing to do.

There are however some issues I have with OAuth2 that I describe in this post. To summarize is that I feel I lack the knowledge about OAuth2 to currently implement anything with it and I haven't had the time to look it up and how the different authentication strategies work. My vision of the API was to have a united API across all boards, and if OAuth2 can provide such strategy (where a developer doesn't need to register their application with every forum) it's all good.

Input needed
It would be nice with some input of what kind of API we actually want. I realized far too late that I probably wasn't very clear with what kind of API I personally wanted, one where a developer can create one application that works with every board (that has the API turned on, of course), and that's the reason why I didn't chose OAuth2 to begin with, as with my limited knowledge all I could see when reading about OAuth2 was strategies that required every application (client) to register themselves by the developer. If that's the case then it's against the vision I had from the start.

But it isn't up to me to decide if this is the API we want, since the API is a complex feature it needs to be decided what kind of API we want, if it should be an API that works everywhere without registering, or an API that only works on single forums where the client happens to be registered. Therefore I ask for ideas, input and knowledge about it

[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.