1. Home
  2. Ideas

Talkyard API?

By KajMagnus @KajMagnus2018-08-08 05:37:40.626Z

What API endpoints could be useful to you? What are your higher level goals, with calling them / what do you want to accomplish?

  • 14 replies
  1. Matthew Rafuse @halo43562018-08-08 09:54:19.876Z

    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.

    1. KajMagnus @KajMagnus2018-08-08 13:41:17.489Z2018-08-08 13:55:54.438Z

      Is 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.

      1. Matthew Rafuse @halo43562018-08-08 14:03:04.529Z

        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?

        1. 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-Key HTTP 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?

          1. Matthew Rafuse @halo43562018-08-08 14:16:52.087Z

            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?

            1. 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 a X-Talkyard-Requester-ID header, 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.

              1. Matthew Rafuse @halo43562018-08-08 14:33:27.382Z

                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.

                1. 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.

                  1. Matthew Rafuse @halo43562018-08-08 15:45:19.932Z

                    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 :)

    2. In reply toKajMagnus:
      Matthew Rafuse @halo43562018-08-08 11:31:26.179Z

      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.

      1. 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 /-/reply and /-/create-page, respectively. — I think getting the session cookie (SSO) is the hard part.

        1. Matthew Rafuse @halo43562018-08-08 14:04:47.097Z

          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.

          1. 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 update to 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.

            1. Matthew Rafuse @halo43562018-08-08 14:23:29.405Z

              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.