DEPRECATED: How to Create Pages and Categories and Post Replies via API
[Update, 2021-11-05] This API, /-/v0/upsert-simple, is now deprecated. Instead, there's a new Do API, at /-/v0/do, which lets you create pages and replies — see How to create Pages and Comments via the API. You can do other things too, e.g. having someone Like an idea and subscribe to it, see: How to Like and Subscribe to Pages via the API.
[/Update]
Via Talkyard's Upsert API, you can create pages, categories and replies. (Editing / updating pages via API: Not yet supported.)
First, read about the Talkyard API authentication, including about how to enable the API.
And check out the API shorthand syntax.
External IDs and references
Below, you'll see fields like extId: ... and categoryRef: ... and authorRef: 'username:...'. What's that?
Well, Talkyard needs to know if, later on when you call the API again, if you're referring to the same thing. Because maybe you don't want to create a new page — maybe you instead want to update a page you've created already. Therefore you can specify your own IDs — and, from Talkyard's perspective, these IDs aren't Ty's own; they are "external" ids.
So, when you create a page, you specify extId: "aaa" — then, to update that page, call upsert-simple again with the same extId: "aaa".
Also, if you've created your own categories, you can give them your own "external ID".
And when creating a page, to choose in which category to place it, use the categoryRef field ("ref" here means "reference", — you're referencing a category, rather than including it inline).
For example, categoryRef: "extid:your-category-id". Note that the category ID is prefixed with extid:, so Talkyard knows what type of ID follows. Because in some cases, maybe it's more nice to use Talkyard's internal ids, instead of your own. (Then the prefix would probably be tyid: (for Talkyard ID))
And here: authorRef: 'username:some_username' the prefix username: tells Talkyard that what follows is someone's unique username — but you could also do: authorRef: 'extid:user_external_id' if you'd rather reference users, via their IDs in your database, than via usernames.
Creating Pages via API
POST /-/v0/upsert-simple {
pages: PageToUpsert[],
}
interface PageToUpsert {
// id: Internal ID generated by the server
extId: `${ups_page_ext_id}`,
pageType: PageType,
categoryRef: `extid:${category_ext_id}`,
authorRef: `username:${some_username}`,
title: St,
// slug: generated by the server, derived from the title
body: St,
bodyMarkupLang?: 'HTML', // default is CommonMark
}
const enum PageType {
Question = 10,
Problem = 14,
Idea = 15,
Discussion = 12,
}
By setting categoryRef and authorRef to the appropriate values, you can choose in which category it'll appear, and who the author will be.
End-to-end tests
If you'd like to see some code:
- Upserting pages
https://github.com/debiki/talkyard/blob/48044724503ef231848ee7af19ae66f1b71ca43e/tests/e2e/specs/api-upsert-pages.2browsers.test.ts#L153 - Upsert pages, and set author to a user that got created via the Single Sign-On API:
https://github.com/debiki/talkyard/blob/48044724503ef231848ee7af19ae66f1b71ca43e/tests/e2e/specs/api-w-sso-upsert-pages.2browsers.test.ts#L116 - Upserting pages can generate notifications for those who want:
https://github.com/debiki/talkyard/blob/48044724503ef231848ee7af19ae66f1b71ca43e/tests/e2e/specs/api-upsert-page-notfs.2browsers.test.ts#L168
Posting Replies via API
Todo: Write docs
End-to-end tests
- Posting replies via API, to a "manually" via the UI created page, and to another page created via the API
https://github.com/debiki/talkyard/blob/48044724503ef231848ee7af19ae66f1b71ca43e/tests/e2e/specs/api-upsert-posts.2browsers.test.ts#L168
Creating Categories via API
Todo: Write docs
End-to-end tests
- Creating and updating categories via API, and creating a new topic (just to verify it works in the upserted categories), https://github.com/debiki/talkyard/blob/48044724503ef231848ee7af19ae66f1b71ca43e/tests/e2e/specs/api-upsert-categories.2browsers.test.ts#L137