PHPBB3-11595 - API

Discuss requests for comments/changes posted in the Issue Tracker for the development of phpBB. Upcoming releases are 3.2/Rhea and 3.3.
Post Reply
User avatar
galaxyAbstractor
Google Summer of Code Student
Posts: 17
Joined: Sun Sep 25, 2011 7:40 pm

PHPBB3-11595 - API

Post by galaxyAbstractor » Mon Mar 26, 2012 11:05 pm

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: 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 :)
Last edited by galaxyAbstractor on Sat Mar 21, 2015 3:30 pm, edited 2 times in total.

User avatar
A_Jelly_Doughnut
Registered User
Posts: 1780
Joined: Wed Jun 04, 2003 4:23 pm

Re: [RFC] API

Post by A_Jelly_Doughnut » Tue Mar 27, 2012 12:40 am

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

User avatar
callumacrae
Infrastructure Team
Infrastructure Team
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Re: [RFC] API

Post by callumacrae » Tue Mar 27, 2012 5:38 am

+1 to most of the idea, but I don't think stuff like *CP should be added.
Made by developers, for developers!
My blog

User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC] API

Post by naderman » Tue Mar 27, 2012 12:14 pm

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.

User avatar
callumacrae
Infrastructure Team
Infrastructure Team
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Re: [RFC] API

Post by callumacrae » Tue Mar 27, 2012 12:19 pm

naderman wrote: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']);
});
Made by developers, for developers!
My blog

User avatar
galaxyAbstractor
Google Summer of Code Student
Posts: 17
Joined: Sun Sep 25, 2011 7:40 pm

Re: [RFC] API

Post by galaxyAbstractor » Sat Apr 07, 2012 4:15 pm

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.

User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC] API

Post by naderman » Sun Apr 08, 2012 11:53 am

Seems like a good way to do this.

_hsr
Registered User
Posts: 42
Joined: Mon Mar 26, 2012 7:06 am

Re: [RFC] API

Post by _hsr » Wed Apr 11, 2012 5:56 am

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.
There is a text here !

User avatar
galaxyAbstractor
Google Summer of Code Student
Posts: 17
Joined: Sun Sep 25, 2011 7:40 pm

Re: [RFC] API

Post by galaxyAbstractor » Wed Apr 11, 2012 8:40 am

_hsr wrote: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
Registered User
Posts: 11
Joined: Mon Apr 04, 2011 12:42 pm

Re: [RFC] API

Post by Jocelyn79 » Thu Apr 19, 2012 4:50 pm

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.

Post Reply