How to interact with discourse platform using REST API's

Siddhu_Dhangar · May 20, 2020, 10:13am

This is a simple documentation which i made for you. here i am going to show you how to interact with discourse platform i.e https://metastudio.org/ using discourse API’s.This documentation gives you a overview of a DISCOURSE APIs using curl.

For interacting to discourse platform using API’s, one important thing you need is API Key. Without API key you can not interact with discourse platform i.e https://metastudio.org/

To create an API key, Make sure you are admin of the site. once you have a proper access to the site, then follow the below steps as shown in the images to create an api key:

[size=6]GET API’s:[/size]

The GET request simply looks like this, for getting a specific resources. Once you have your API Key you can pass it in along with your API Username as an HTTP header like this:

Get some groups:

curl -X GET "https://metastudio.org/groups.json" -H "Api-Key: 9179xa8f80c6943ead9c7ab19ad3c67f542838a8ae2a854910d3a1dxd14773cf" -H "Api-Username: username"

Most API endpoints provide the same content as their HTML counterparts. For example the URL /groups (i.e ChatShaala) serves a list of groups, the /groups.json (i.e https://metastudio.org/groups.json) API provides the same information in JSON format.

Get some categories:

curl -X GET "https://metastudio.org/categories.json" -H "Api-Key: 91798a8f80c6943ead9c7ab19ad3c67f542838a8ae2a814910d3a1ded14773cf" -H "Api-Username: username"

URL /categories (i.e ChatShaala - chatShaala for life-long STEM Education! Collaborative Open Online and Ongoing Learning through STEM games, activities and projects and earn badges from the referees!) serves a list of categories, the /categories.json (i.e https://metastudio.org/categories.json) API provides the same information in JSON format.

Get a single Topic:

curl -X GET "https://metastudio.org/t/project-ideas-wiki-page/3801.json" -H "Api-Key: 91798a8f80c6943ead9c7abe9ad3c67f542s38a8ae2a854510d3a1ded14773cf" -H "Api-Username: username"

Note: Api-Username: name of the registered user of discourse platform i.e https://metastudio.org.
Api-key: Api key can be created by admin only.

[size=6]POST API’s[/size]

The Content-Type for POST and PUT requests can be set to application/x-www-form-urlencoded , multipart/form-data , or application\json .

Create a single topic:

curl -X POST "https://metastudio.org/posts.json" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: 91798a8f80c6943ead9c7ab19ad3c17f542838a8ae2a854910d3a1ded14773cf" \
-H "Api-Username: username" \
-F "title=new topic creating for testing" \
-F "raw=desc of new topic creating for testing" \
-F "archetype=regular" \
-F "category=5"

Likewise you can use PUT and DELETE API’s.

Refer below urls for more info:

Network request details — Firefox Source Docs documentation

when js framework is finalized to this project, after that i will make one more documentation on that framework. where i will show you how to write api calls using that framework.

Please feel free to ask any query.

punkish · May 21, 2020, 10:33am

I would like to suggest that all API routes be available under a single, unified prefix. My suggestion would be /api/v<version>/, so for example

https://metastudio.org/api/v1/groups.json
https://metastudio.org/api/v1/posts.json

This ensures a clean separation from the API endpoint and the HTML endpoint.

punkish · May 21, 2020, 11:25am

@Siddhu_Dhangar @surendra @gnowgi Please create an API key for me. That way I can tinker around with the API as well. Many thanks.

surendra · May 22, 2020, 7:44am

I will shortly create a api key on testing discourse testing instance and share details on telegram.

Siddhu_Dhangar · May 22, 2020, 8:05am

hi,
@punkish it is a good suggestion actually. but As you know that metastudio site is running on discours platform and all discourse apis have been developed by discourse team.
To modify all those urls of apis, we will have to rewrite all the apis with new url prefix which is “api/v1/” using discourse plugin.

what should we do now ? should we use existing and well tested apis for developing the app ? or should we write new apis with “api/v1/” prefix ?

GN · May 22, 2020, 10:57am

For content that is public, we do not need an API key to get the data. If a topic is published under a private group etc, it is not possible to get the data unless the user is eligible to see the data.

For put commands we certainly need API key. So, to get a simple readonly UI, we do not need much. With this data, you would know how to manipulate the DOM, and render the content in HTML through JS.

punkish · May 22, 2020, 3:16pm

Discourse has a boatload of settings on the server side. You might want to check if you can change the prefix of the API endpoint. If yes, great, do it. If not, well, then we live with that restriction.

punkish · May 22, 2020, 3:18pm

ah, so let’s us clarify the remit – you want a read-only application. Absolutely no user feedback. Just read only.

But then, in that case, why even bother making anything? There are many lightweight RSS readers that do the job very well. Actually, I now exclusively read Stemgames via an RSS reader on my phone and laptop. I have to go the the actual website only when I want to respond.

Just learning how to code is a good enough goal, and I have no quibbles with that. But I hope that is learn to everyone involved.

Of course, I could be completely wrong in my assessment above so do set me right as needed.

GN · May 22, 2020, 6:57pm

No, what I meant is not a read-only-client. I only wanted to point out that data of public resources can be obtained without API keys. Since @Siddhu_Dhangar’s examples for get command also supplies API key, I wanted to mention that it is not necessary for reading public data.

Also, those who wanted to get the UI ready need not wait till all the functions are written. The learning required for CSS and HTML, and a little bit JS part of the App can be done. Another team can begin to write functions to add replies and posts, likes etc.

surendra · May 25, 2020, 4:23am

It will look clean for sure.

But presently our main focus should be on increasing the performance & removing the boatload.

If we get into changing api url prefix, everytime the discourse server is upgraded there are chances we might be break the instance. (At least one discourse upgrade is available every month)

Also changing the API URL prefix will not have any change on data that is fetched and also will not provide any kind of optimisation. Given the time constrain I suggest we can skip this part for now.

Siddhu_Dhangar · May 27, 2020, 12:06pm

Problem:

I am able to get the data from by using the API with a status code 200 but while parsing it, the local server crashes with an error: [Uncaught SyntaxError: Unexpected end of JSON input at JSON.parse].

It is happening while trying to get users, posts, or even categories.

Solution:

const fetch = require('node-fetch');
let url = 'https://metastudio.org/groups.json';

let settings = { method: "Get" };

fetch(url, settings)
    .then(res => res.json())
    .then((json) => {
        console.log(json.groups);
        console.log(json.groups[0]);
    });

===========================================================

const fetch = require('node-fetch');
let url = 'https://metastudio.org/categories.json';

let settings = { method: "Get" };

fetch(url, settings)
    .then(res => res.json())
    .then((json) => {
        console.log(json);
        //console.log(json);
    });

Hi Bir,

I am able to fetch the groups and categories data successfully using node-fetch library. can you try to replace your code with this ? and try once again.
i hope this answer helps you.

surendra · May 28, 2020, 8:10am

@punkish
@f20180261
@GN @Siddhu_Dhangar @mahesh.tirthakar

Presently you can use below URL to view & test the site.
https://apptest.metastudio.org/

SSH access and code build related details to @f20180261 will be shared soon as I am working on it.

Siddhu_Dhangar · June 17, 2020, 4:23am

@gnowgi @surendra @mahesh.tirthakar @f20180261

Yesterday i asked discourse team about the login issue. they suggested me that try to use SSO(Single Sign ON) or certificate pinning. Today, I am looking Keycloak SSO which was already deployed by surendra two months ago. I am trying to understand this keycloak SSO like how it works and how we can authenticate the registered users which are already registered on metastudio site. For this i am taking surendra’s help.

References:

https://www.keycloak.org/docs-api/5.0/rest-api/index.html

Siddhu_Dhangar · June 17, 2020, 4:07pm

@gnowgi @f20180261 @surendra @mahesh.tirthakar

I tested the keycloack (SSO) integration with node js locally. I took clone from the following git url i.e GitHub - austincunningham/keycloak-express: 🔓 Express App that uses Keycloak to secure API endpoints.

I followed all the instructions which was given on the above github url for testing the integration part. some settings need to be configured on keycloak. so i did all the required configurations. finally login part is working fine.

References:

GN · June 17, 2020, 4:12pm

Since we want to use a single sign on across all our platforms, this is the way to go. Thanks for exploring this. Please pass this or send a patch to the App.

Siddhu_Dhangar · June 17, 2020, 4:30pm

If i am wrong then please correct me. From now on, In lightweight app, login and registration part will be handled by keycloak SSO only. right.

GN · June 17, 2020, 4:32pm

Not only for the app, but for all other services we might deploy, we shall use SSO.

@surendra is https://interx.metastudio.org also using SSO? If not, can we use the same?

surendra · June 18, 2020, 8:08am

Yes SSO can be integrated with https://interx.metastudio.org.

surendra · June 18, 2020, 8:18am

@f20180261 @GN @Siddhu_Dhangar @punkish @mahesh.tirthakar

We need OpenID connect (an extension of Oauth) integrated with our apptest.metastudio.org.

There are many users on metastudio.org who do not have password login, they always using login with OpenID connect which is a Keycloak instance (This instance has login with google/facebook or password based login).

Please look regarding integration of keycloak with nodejs. There will be a library already available for it.

Below share are links that may help getting started.

Enterprise Web App Authentication Using Keycloak And Node.js | by Ramandeep Singh | Medium (already shared by siddhu above)