Talkyard API?
What API endpoints could be useful to you? What are your higher level goals, with calling them / what do you want to accomplish?
- ?@anon1640558225
Mainly I'm interested in being able to list posts, get post information, submit posts and add comments, as well as creating users through the API.
The high level goal is to use talkyard as a support forum for a product. The posts and such should be able to be viewed in that product without needing to go to the site itself.
KajMagnus @KajMagnus2018-08-08 13:41:17.489Z2018-08-08 13:55:54.438ZIs this maybe a bit like embedding different Q&A topics on different product pages? Or is there only one product page, and maybe embedding a whole forum, in an iframe directly on that product page, is similar to what you have in mind? — Then you'd be able to list & submit posts and comments (via the iframe ... a bit different from using the API though).
There are embedded comments, so in a way, single topics can be embedded already. Embedded comments example: https://www.kajmagnus.blog/new-embedded-comments. However, embedding a whole forum, currently doesn't work.
- ?@anon1640558225
We are looking to list topics similarly to talkyard, but more tightly integrated into our own product. The bare minimum would be to list existing topics (which is currently supported via
/-/list-topics), and create new topics, which as discussed below currently is difficult to do due to the session cookie.Would I be able to intercept the session cookie in any way?
- KajMagnus @KajMagnus2018-08-08 14:14:14.961Z
Maybe an API key is what you need? It seems to me that usually to access/manipulate a software system via an API, one gets an API key, rather than a login session cookie, and then one can do "anything" via that API key. (Intercepting a session cookie — hmm sounds complicated to me.)
Maybe there could be an
X-Talkyard-API-KeyHTTP header that lets your server(s) do "anything they want"?New topics — are they to be created by real people logged in to your system? And get real human author names like Alice and Bob and Joe and Jane? Or is the topic author a machine, like
system?- ?@anon1640558225
An API Key is exactly what I am looking for. I only really asked about the session cookie as an API Key was not currently implemented. The topics would likely have real names of a sort - could we give a user id and have it seem like they created the topic? If not, it would likely be sufficient to be able to create topics under say a "Talkyard bot" user - we can reference the users in the post itself.
EDIT: Maybe API keys could be generated on a per-user basis?
- KajMagnus @KajMagnus2018-08-08 14:30:56.610Z
Maybe if your server sends a request with an API key, and includes a
requesterId: ....JSON payload field, or maybe aX-Talkyard-Requester-IDheader, then the server can run the request, with the permissions of the user with that ID. So if you have the API key, your server can do requests on behalf of anyone.Many API keys, one per user — hmm that can be useful for bots, later on? For example, someone creates a bot. And the bot says / does weird things from time to time, isn't totally trusted. So it should be restricted to a certain chat channel. It could get its own user ID, and and API key for that user ID — and this bot user ID & associated key then has access to that chat channel only.
- ?@anon1640558225
So if you have the API key, your server can do requests on behalf of anyone.
While this would work fine for me, the security implications aren't great. One key gets loose and your entire forum is compromised. If you got a user-specific API key and this key only gave you access to that user's account, the damage is lessened.
- KajMagnus @KajMagnus2018-08-08 14:59:12.424Z
I can look into this now the nearest days / during the weekend and see how much work this is. List topics, create topic, + post replies.
About security: Other systems I come to think about (AWS, DigitalOcean, Scaleway) have a single key that lets one do everything, as far as I remember & can see now when I had a quick look at D.I.'s and Scaleway's docs. ... Anyway I agree with you that it would be / seems safer with more granular "smaller" keys. I can think about if maybe it's as "easy" to do things in the one-key-per-user way, as in the one-single-super-key way.
- ?@anon1640558225
Really for me I don't mind the single API key that is set in admin settings, that's perfectly fine, so long as we can change the API key if it is ever compromised. If that's easier to implement then I'm fine with going that route :)
- ?In reply toKajMagnus⬆:@anon1640558225
From my research it looks like it may be difficult to use the existing API for creating posts, as I don't see how authentication works or could work outside of the browser, currently.
- KajMagnus @KajMagnus2018-08-08 13:52:19.554Z
About authentication: You're maybe looking for Single-Sign-On? So, if a user is logged in, at your site, then the Reply button etc will work immediately, and the users will get the author name & email-notification-address they have already over at your site?
SSO hasn't yet been implemented, ... I started a bit, a while ago, for embedded comments.
About posting comments and new topics: Post
{ pageId: …, postNrs: …, postType: …, text: … }and{ pageRole: Discussion, pageStatus: Published, pageTitle: …, pageSlug: …, pageBody: … }to/-/replyand/-/create-page, respectively. — I think getting the session cookie (SSO) is the hard part.- ?@anon1640558225
That's what I've discovered from my research - I'm just not sure how to intercept the cookie as the login code calls some internal functions I couldn't find in the repo. Any tips there?'
SSO would be great as well, only issue is the product isn't a website.
- KajMagnus @KajMagnus2018-08-08 14:21:48.966Z
About "Any tips here" — I now mentioned maybe using an API key, in this comment above.
About "internal functions I couldn't find in the repo" — there's a Git submodule with a Data Access Object implementation: https://github.com/debiki/ed-dao-rdb — some login methods are located in there — maybe those are the ones you didn't find? (one needs to run
git submodule --init updateto download them). Or if the login functions are related to OpenAuth, then maybe you didn't find them because they're located in the Silhouette OpenAuth plugin.- ?@anon1640558225
Ahh yeah didn't run that. In any case, an API key would be far more suitable for my use case than trying to intercept a session cookie or something. Far more reliable.
- JIn reply toKajMagnus⬆:@jhkings
I'd like to access the issues and be able to create a dashboard that shows the issues along with the number of user reported, maybe even a historical of count by the hour. Similar to https://downdetector.com/status/battle-net. Also, I'd like to be able to add custom fields to the issues, such as version string and location.
Thank you!- KajMagnus @KajMagnus2018-09-26 04:19:01.731Z
a dashboard that shows the issues along with the number of user reported
You mean the total number of open issues? Like, "currently there are 123 open issues." + a graph that shows how this number changes, over time? This would then, in the simplest version, be something like an endpoint
/-/v0/count-topics?isWaiting=true&type=problem? + maybe a query param:&when=2018-09-25-2359(But you don't have in mind to show, for many different issues, how many people have reported each particular issue? Like so:
"""
Current issues:- Some title, reported by 12 people
- Another title, reported by 34 people
- A third title, reported by 56 people""" )
add custom fields to the issues, such as version string and location
I'm going to re-implement tags, later on. Custom fields — that could maybe be tags, with values?
Yes, more like what you said. A list of issues and the number of people have reported on each issue. Perhaps a button to click to say I have experience the issue, so that's one end point call to tally up. As for the geo points, it's for the heat map. Which locations are experiencing the issue and how far and how fast it's spreading.
My idea is to let people get an idea how severe the issue they are experiencing and if it's something common or isolated. At which version did the issue started to show up and which version the issue was resolved.
Thank you!
- JIn reply toKajMagnus⬆:@jhkings
@KajMagnus why not use Postgraphile to expose the data as the back end is Postgres?
- KajMagnus @KajMagnus2018-10-17 19:35:45.020Z
Interesting, hadn't heard about Postgraphile bepore. Some things come to mind:
1) Database changes that break people's integrations. I'm worried that people's integrations with Talkyard will break, when I rename / restructure database columns and tables. The HTTP API is simpler to keep backwards compatible. I can just add a new function with the
/-/v1/URL path prefix, and keep the old one unchanged, at/-/v0/.2) Access control and performance. The database is multitenant (many communities in one single database), so Postgraphile would need to be carefully configured, so as not to accidentally allow access to the wrong tenants (communities). Also, if people could send arbitrary queries to the database, via Postgraphile, they could Denial-of-Service attack the database.
I'm thinking that therefore Postgraphile is impossible to use, for the SaaS hosting service.
However, if you run Talkyard on-premise, then, there shouldn't be any problems with access control or DoS attacks (since it's all your own database and contents). Also, if you disable automatic upgrades, then you could wait with upgrading, until your integrations are compatible with any database changes.
Maybe there could be documentation and sample Docker-Compose config for adding a Postgraphile Docker container and connect it to the database. People who install on-premise, can then copy-paste the sample config into the Docker-Compose file. And in that way get API access to everything in the database. ... Plus a warning about this being a bit fragile, in case the db structure changes.
B.t.w. how do you use, or are thinking about using, Talkyard? On your own server, or via the SaaS hosting?
I'm running Talkyard on Digital Ocean. With the recent offering of hosting Postgres database, I really would like to explore a set up where I can manage all components of Talkyard, Postgres, and Postgraphile as well as my website on Digital Ocean. I would like to use Talkyard for the forum as well as for discussion on blog posts.
Thanks!- KajMagnus @KajMagnus2018-11-01 11:32:15.332Z
Ok, thanks for explaining. You want to (or have already) connect to an external PostgreSQL database then, managed by DigitalOcean? And you don't need the
rdbcontainer or database storage volume then, I suppose. Plus maybe add a Postgraphile container?How do you host your blog — is it behind a reverse proxy with HTTPS? (Maybe Traefik or Caddyserver?) Should Talkyard also be behind the same reverse proxy? Maybe you want a Docker-Compose (?) file that includes your blog, plus the Talkyard containers? Any thoughts about Docker Swarm or Kubernetes?
- Progresswith doing this idea
KajMagnus @KajMagnus2019-05-01 04:53:16.678Z2019-05-12 20:57:39.805ZThere's now a Single Sign-On API, read more here: https://www.talkyard.io/-121/single-sign-on-and-api.
(The other things discussed / suggested here haven't yet been implemented though.)So, closing this. Other API endpoints can be added, upon request. (Well some things have been suggested already, ... that was like half a year ago. If you remind me again, then, that you still want / need those endpoints.)