XF 2.1 REST API

Welcome to another HYS for 2.1 and this one's a biggie. If you haven't seen the previous entries about what's coming in XF 2.1, check them out here.

Although Halloween may be over, why not trick the "Watch forum" link into giving you a treat, by getting it send you an email whenever we post about new things in the pipeline.

As I write this, our most popular suggestion was a REST API and with 2.1, it's here. While this is a fairly developer-focused feature on its own, it opens up many more integration options. This will make it easier to get data into or out of XenForo, without having to understand the underlying PHP framework that XF is built on.

The API breaks down into a few distinct components, so let's look at those in turn.

 

[Sim]

@Chris D / @Mike how functionally complete is the API at this point?

I know some SaaS apps aim to build a complete API (which their web front end uses), which theoretically means that you can provide your own purpose build front end and bypass that provided for the app.

(example: SparkPost always release functionality via their API first and then code the admin UI later - since their web UI uses their API)

So, for example, if someone wanted to write a Vue or React JS front-end for XenForo, would they be able to replicate the back-end functionality of the forum using the API?

Just curious

 

[Chris D]

Question: is this generic in a way that eg. official addons like Media-Galery would be accessible as well ?

It's generic in that any add-on can add its own API endpoints. That reminds me... we probably do need to add some to XFMG and XFRM...

 

[Ozzy47]

Wonderful news, this will help an existing project ten fold.

 

[Chris D]

@Chris D / @Mike how functionally complete is the API at this point?

I know some SaaS apps aim to build a complete API (which their web front end uses), which theoretically means that you can provide your own purpose build front end and bypass that provided for the app.

So, for example, if someone wanted to write a Vue or React JS front-end for XenForo, would they be able to replicate the back-end functionality of the forum using the API?

Just curious

It certainly doesn't cover absolutely everything, at this point. Though we deliberately scaled back some bits due to time constraints in the knowledge that actually adding new API endpoints wouldn't necessarily bring up any backwards compatibility issues. So if there are obvious things missing, obviously let us know in the beta/RC stages if possible, but otherwise things can get added iteratively, even in 3rd point releases if we wish to.

I would say the most important stuff is there.

 

[DroidOne]

Praise be! This is fantastic news. I was already content with all of the XF 2.1 news, but this takes it to another level (...over 9000!).

 

[Radhi]

Thank you!!

 

[FoxCom]

Shut up and take my renewal money!

 

[Mian Shahid]

 

[ibnesayeed]

Let's look at /api/threads/123/ as an example. When you request this URL, what happens depends on the method used:

• GET - this will get information about the thread with ID 123. If you pass the with_posts parameter, we'll also include a page of posts.
• POST - this will update the thread's information, such as the title or whether it's sticky. Any elements you don't want to update can be omitted as parameters. Note that this is not for replying to this thread.
• DELETE - as you might expect, this allows you to delete the thread. Parameters can be passed in to control the type of deletion (hard/soft), the reason provided, etc.

Why is POST being used on an individual resource to update it? While I understand it is not a REST API in pure sense that utilizes HATEOAS principles, instead it is just an HTTP API, I think it is still worth respecting some conventions for easier understanding. For partial updates generally PATCH method is utilized and POST is used on the parent entity to create a new resource.

• POST /api/threads - should create a new thread where the ID of the resource is determined by the server
• PATCH /api/threads/123 - should partially update the thread with ID 123

 

[Alpha1]

(This is not targeting an OAuth style setup, though clearly there is groundwork there.

I think for many people Single Sign On between 2 xenforo installs or XF + another script would be the big one. REST API is really great to see added, but if you see any way to include Single Sign On , then that would be a game changer of the first category.

Also: can account upgrades be exposed?
How about custom fields updating/writing?

 

[Arty]

This is awesome!

You should consider making CMS based on XenForo code. Its just too awesome. I'm sure many users of WordPress, where 90% of themes/plugins are written by monkeys and are full of exploits, would switch to well written framework.

 

[Xon]

Keys are only created by super admins at this point. (This is not targeting an OAuth style setup, though clearly there is groundwork there.)

So no, this can't be disabled in the core. Of course, if you write custom code to generate keys, then that would be a different story.

In that case; Per-user REST key management UI. As if this is ever intended to become a per-user controlled thing, I think a solid key management in core will be needed.

 

[Lukas W.]

Keys are only created by super admins at this point. (This is not targeting an OAuth style setup, though clearly there is groundwork there.)

That is a big bummer and renders a large portion of potential use cases undoable...

 

[The Dark Wizard]

That is a big bummer and renders a large portion of potential use cases undoable...

Clearly, ThemeHouse and @Xon need to race to see who is going to do API Essentials first.

This is awesome!

You should consider making CMS based on XenForo code. Its just too awesome. I'm sure many users of WordPress, where 90% of themes/plugins are written by monkeys and are full of exploits, would switch to well written framework.

@Mike @Chris D I see those likes. You guys never like suggestions, don't want people to think you are doing something unless its coming.

 

[Slavik]

You should consider making CMS based on XenForo code. Its just too awesome. I'm sure many users of WordPress, where 90% of themes/plugins are written by monkeys and are full of exploits, would switch to well written framework.

Providing a solid framework doesnt remove the risk that those "monkeys" would simply bring their bad code to the good framework

 

[Chris D]

@Mike @Chris D I see those likes. You guys never like suggestions, don't want people to think you are doing something unless its coming

We were mostly just liking the “this is awesome” bit

 

[The Dark Wizard]

We were mostly just liking the “this is awesome” bit

I figured lol.

I just wanted to point that out and have some fun, I never join in on these conspiracy theories or whatever on what is coming out. Must be the madness of not yet sleeping (it is 8:31am) haha.

 

[DragonByte Tech]

When accessing the API, you will always be acting as a particular user. This will be used to know who is creating content or what permissions to use, though there are some exceptions to this which we'll get into later. Therefore, there are three types of API keys
[...]
User keys. These keys are tied to a particular user. All actions (such as creating a thread) will be attributed to this user and their permissions will be taken into account.

Am I to understand that if I wanted to have a button that lets users create an API key for their eCommerce information for use in addons like "Install & Upgrade", I could programmatically create a "user key" with new, custom scope(s) for accessing eCommerce info, and any requests using that API key would automatically be tied to that user's account?

If so, that's perfect

I think I'll pre-define my routes with /api/ and using an Api sub-folder for these controllers just now to minimise the amount of work I have to do when this is released


Fillip

 

[Jake B.]

The API key you generated must be passed in via a custom XF-Api-Key header added to your request.

Why not use the Authorization header, which is a standard?

 

[Mike]

It's also not passed through to PHP in certain configurations, annoyingly.