Write-enabled API (Brainstorming)

julian

Hey all,

Re: The Road to v0.5.0 and Beyond -- Write APIs

Lots of people have written in to let us know that they want deeper integration with NodeBB in some form. Right now, that's possible through plugins, although it's got a fairly high barrier to entry (you'd have to learn Node.js, for one, and lots of people aren't willing to do that).

We always mention that we have a public "read-only" API available for consumption (like this one!), though it'd be nice if a JSON/RPC write API were added so applications can ping NodeBB to add topics by sending a POST.

Some Thoughts

The Write API will be available as a plugin
This plugin is not going to make it in for v0.5.0, sorry
Security will always be an issue
- I was thinking basic key-based authentication (create a key in the ACP page, send that key in the POST body for authentication)
- HTTPS will be required, although right now I can't think of a way to force it (or detect if it's in use...)
- IP based limitation would also be there, so you can limit requests to 127.0.0.1, for example
- Does anyone have need for OAuth authentication? Seems like a lot of extra work for little gain.
Functionality would more or less mimic what's available with NodeBB
- Topic creation
- Topic posting

(Writing this is making me think about webhooks as well, but I've already got enough on my plate )

fyhao

Enable read/write API, the better, notification of new topic / real time streaming. For developer make it like registering an application, have an API key and secret, REST-styled API / JSON.
For normal user they provided options whether to install the application.

julian

Thanks for your thoughts -- for most admins, they wouldn't want a write API layer installed, so it's strictly an opt-in process. Better for security, anyhow -- no holes to exploit if the entire layer isn't even there, right?

I'll have to look into key/secret vs. just key. It would be pointless to require a secret in addition to a key for a client-facing app (since the code could just be decompiled to find the secret), plus there's a bit of a development cost to supporting it as well (encrypting and decrypting using secret, etc...)

a_5mith

@julian said:

HTTPS will be required, although right now I can't think of a way to force it (or detect if it's in use...)

Could you use HSTS for this?

julian

Sure, although HSTS is only a header, meaning it's up to the end user implementation (i.e. the browser) to comply.

a_5mith

@julian Surely that's all you need to do though, if the browser/end user doesn't comply, they don't get access to it. As HSTS is ignored by non https.

Or am I misinterpreting what this does.

RefinedSoftware

I did a quick search through the NPM and here are some MIT Licensed modules can could be used or drawn upon for inspiration.

https://www.npmjs.org/package/restify-https
https://www.npmjs.org/package/https-aware
https://github.com/substack/node-https-detect

esiao

Isn't the API write already ? I mean I used it to store the settings of my plugin maybe you mean without having to use a plugin. This could be a good thing but this means also needing some access token and in that case maybe could we have a super user token (for accessing hidden information like core groups) and a user token for normal interractions.

pwFoo

I could need a integration of NodeBB to my planned site.
Read topics, boards and user info should be no problem. NodeBB read only API seems to do that job.

But is it possible to process login or user registration via API (in the future)? My php application could try to check NodeBB login / user. If NodeBB login via API was successfully also the CMS user gets logged in. If the user doesn't exist at CMS side (not logged in before) an account would be created.

So my website could use NodeBB user backend if login / logout via API will be possible in the future
HTTPS shouldn't be needed because the api call comes from the local machine?

julian

Have you looked into the blog comments plugin?

pwFoo

@julian
Not so far...
Looks nice at NodeBB blog
If I need a comment integration that will be a great solution!

But my main site also works with authentification and permissions. So I have to sync login state / user accounts.
The main site is Processwire based and I'm build a login module. So the module (php coded) need to process a NodeBB login and get a result about success.

I haven't any experience with nodejs / nodebb coding, so I don't know how it could be done.

psychobunny

So I have to sync login state / user accounts.

Have a look at this plugin:

GitHub - julianlam/nodebb-plugin-sso-oauth: NodeBB Plugin that allows users to login/register via any configured OAuth provider.

NodeBB Plugin that allows users to login/register via any configured OAuth provider. - julianlam/nodebb-plugin-sso-oauth

GitHub (github.com)

You will likely have to modify it a bit to fit your solution, but it's definitely doable

yamill

this would be awesome. a write api would allow us to create some nice apps that are integrated with nodebb

julian

Thanks @yamill -- this is definitely something that's been on our minds for the next version (not that we're thinking that far ahead yet... still 0.5.0 to be released)

yamill

@julian that's great news! i really love what you guys are doing with nodebb.

pwFoo

Will the planned writeable API include a login / logout (optional Register account) function?

I need something like that to call via PHP or PHP rendered code (JS if client side), because oauth isn't a useable Option.

agarcia17

yes..! this would be amazing!! how's it coming along @julian ?

julian

@agarcia17 in have a proof of concept working, though it needs to be fleshed out a bit.

I'm currently out of town (speaking at a js event in Calgary!), so I'll make it a focus of mine when I get home assuming nothing else comes up!

gabralvia

Would be nice to encode the api at user experience. like restfull.

have a 'createNewCategory' topic inside 'admTool' category, if a mod write a respod with "footbal & rugby" the api create a new category named 'footbal & rugby'.
Each category has a '/proc' topic to acces api funcion over .this category.
to chance my photo i could go to admTool/chPic topic and upload a image.

if the api is themeble can pack the adm routine like moderated or not. Can be 'monarchyed', the api just accept the call of the King login.

babaggeii

Is there an update on the write API? Would be interesting to see how it's coming along.