PHPBB3-11595 - API

Discuss requests for comments/changes posted in the Issue Tracker for the development of phpBB. Current releases are 3.2/Rhea and 3.3/Proteus.
Post Reply
User avatar
callumacrae
Former Team Member
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

[RFC] [API] External API URL structure

Post by callumacrae »

I propose that URLs for the API use the following structure:

Code: Select all

GET /phpBB/api.php/(json|xml)/post/3
GET /phpBB/api.php/(json|xml)/posts
POST /phpBB/api.php/(json|xml)/forum/12
It should be intelligent and rails-like with the controller names (plurals etc).

It should then be dealt with by a file called api/topic.php containing the following:

Code: Select all

<?php

/* DocBlock */

class phpbb_topic extends phpbb_api
{
	// GET /
	public function list() {}

	// GET /:id
	public function get($id) {}

	// POST /
	public function new() {}

	// POST /:id
	public function post($id) {}

	// PUT /:id
	public function edit($id) {}

	// DELETE /:id
	public function delete($id) {}
}
The functions should then return the output as an array or other data, which will then be turned into JSON or XML. This removes the need for tonnes of checks before echos or various formats.

There should be some information available in $this->request:

Code: Select all

$this->request = array(
	'full_url'	=> 'api.php/json/post/3',
	'file'		=> 'api.php',
	'path'		=> 'json/post/3',
	'format'	=> 'json',
	'controller'	=> 'post',
	'data'		=> array('3'),
);
Thoughts?
Made by developers, for developers!
My blog

User avatar
naderman
Consultant
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Berlin, Germany
Contact:

Re: [RFC] [API] External API URL structure

Post by naderman »

If we need to stick json/xml in the URL rather than determining it by Accept header which I'd personally prefer, then it should be as file extension in the end I think.

However I would much prefer we keep this information in the Accept header, as the URI should uniquely identify the resource, and the format only determines representation of the same resource.

See http://programmers.stackexchange.com/a/139741 http://www.w3.org/DesignIssues/Axioms.html

User avatar
naderman
Consultant
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Berlin, Germany
Contact:

Re: [RFC] [API] External API URL structure

Post by naderman »

Please also keep in mind that we typically won't be able to create a new resource with a given id, but will have to auto generate the id as we rely on the database's auto increment feature to generate them. On some DBMS that means inserting an particular id out of order results in an error.

I agree that the request class should either be extended to provide the information you mentioned, or alternatively and I think this might be the better idea, we should start using the Symfony HttpFoundation and/or HttpKernel for the API.

As I would prefer we don't introduce further user facing files, this should be handled through index.php just like extension front controllers are as well.

Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: [RFC] [API] External API URL structure

Post by Oleg »

Accept header, while nice in theory, is rather inconvenient to supply via e.g. curl/wget. Format as the extension should work better in practice.

User avatar
naderman
Consultant
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Berlin, Germany
Contact:

Re: [RFC] [API] External API URL structure

Post by naderman »

curl -H "Accept:application/json" URL and wget --header='Accept: application/json' URL seem rather straight forward?

It'll have to default to something if you don't send an accept header anyway, so unless you want the non-default format you don't even need this.

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

Re: [RFC] [API] External API URL structure

Post by callumacrae »

I prefer headers or file extensions, +1

Why not allow both? Headers should take priority over extension, and it should default to JSON.
Made by developers, for developers!
My blog

Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: [RFC] [API] External API URL structure

Post by Oleg »

naderman wrote:curl -H "Accept:application/json" URL and wget --header='Accept: application/json' URL seem rather straight forward?
Most people would have to read man pages to work this out, as opposed to simply pasting a url.

There are simpler http clients that do not have a provision for passing arbitrary headers, e.g. freebsd fetch(1).

Even working with such urls programmatically is harder as "get url" is a trivial operation in just about anything, and one most people likely have memorized, while "get url while sending a specific header" usually is not. For example, how would you do each of these via php streams?

Another reason to have an extension in the url is when you wget/curl said url you get the file with the correct extension.

User avatar
naderman
Consultant
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Berlin, Germany
Contact:

Re: [RFC] [API] External API URL structure

Post by naderman »

The way to pass a header in PHP to a stream is the following which you will need for anything other than a simple GET request anyway - and I did not have to look this up since I've simply used it before a few times for other APIs.

Code: Select all

$context = stream_context_create(array(
    'http' => array('method' => 'GET', 'header' => 'Accept: application/json')
));
file_get_contents($url, false, $context);
On the other hand this isn't something I would recommend using since PHP's HTTP handling is rather flawed. For example it considers a 201 status code an error which results in a PHP warning which you need to suppress.

Anyway I guess I'll have to live with the extensions if you insist, but can't say I like it.
callumacrae wrote:Why not allow both? Headers should take priority over extension, and it should default to JSON.
That's a really bad idea, imagine someone requesting json via the header from the xml URL, the result would be really unpredictable and confusing either way. That's really why it should be in the header rather than the URL to begin with, as any accept header will have to be ignored if we go for file extensions.

Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: [RFC] [API] External API URL structure

Post by Oleg »

I might be ok with using the accept header if an extension is not provided.

User avatar
MichaelC
Development Team
Development Team
Posts: 889
Joined: Thu Jan 28, 2010 6:29 pm

[RFC] JSON Output

Post by MichaelC »

The world of websites just serving up templated HTML files is over. Now many different types of content need to be served.

Currently, to be able to get data from a forum on another site you either need to develop your own API or connect to the database.

DB Remote Connection - The most practical of the options would be remotely connecting to a DB, but this means that you have to write your own code to submit posts etc, which can cause issues when they are not running on the same version and/or mods are added. You also have the problem that this is fine when the site accessing is allowed DB credentials, but what if it is an end-users device connecting to your site? You don't want to give out DB access.

So, that leaves us with users developing their own API. The best format as it stands, formatting wise to output is in JSON. I propose we build in this functionality to phpBB.

There would be a json.php (or api.php) file in the root of your installation. It would be able to take many parameters such as json.php?view=forum&id=32&start=30&show=15. It would accept both put (requiring auth of course) and pull requests. You'd be able to take all the posts of a forum, or just a certian number (the above would show the topics 30 - 45 in forum 32).

This API can be used for mobile & tablet app developers. Full desktop application developers for Windows, Mac & Linux. It could also be used elsewhere on the sites to show the latest SITEXYZ announcements (I know many sites show phpBB's), or could show the stats of every forum in a network of forums distributed across forums. The possibilities are endless. Currently RSS is used for this purpose but ultimatly that isn't its main purpose and it only allows the pulling of data and not the pushing of data.

Thoughts?
Formerly known as Unknown Bliss
psoTFX wrote: I went with Olympus because as I said to the teams ... "It's been one hell of a hill to climb"
No unsolicited PMs please except for quotes.

Post Reply