Skip to content
Newer
Older
100644 121 lines (100 sloc) 3.76 KB
8eea848 @dhh Add Topics API
dhh authored
1 Topics
2 ========
3
ac615b8 @georgeclaghorn Add support for archiving/activating topics
georgeclaghorn authored
4 Topics refer to anything in Basecamp that can have comments:
8eea848 @dhh Add Topics API
dhh authored
5
ac615b8 @georgeclaghorn Add support for archiving/activating topics
georgeclaghorn authored
6 * Messages
7 * Documents
8 * Forwards
9 * Calendar events
10 * Uploads
4e1fe92 @eileencodes Fix spelling of to-do and to-do list
eileencodes authored
11 * To-do lists
12 * To-dos
ac615b8 @georgeclaghorn Add support for archiving/activating topics
georgeclaghorn authored
13
209e4bd @georgeclaghorn Wordsmith
georgeclaghorn authored
14 Topics will only appear for resources that have at least one comment, except for Messages, which always have topics.
8eea848 @dhh Add Topics API
dhh authored
15
16
17 Get topics
18 ----------
19
ac615b8 @georgeclaghorn Add support for archiving/activating topics
georgeclaghorn authored
20 * `GET /projects/1/topics.json` returns active topics in the specified project.
21 * `GET /projects/1/topics/archived.json` returns archived topics in the specified project.
22 * `GET /topics.json` returns active topics in all projects.
23 * `GET /topics/archived.json` returns archived topics in all projects.
8eea848 @dhh Add Topics API
dhh authored
24
25 ```json
26 [
27 {
28 "id": 1028592764,
29 "title": "Prep the materials before the board meeting with Bezos",
30 "excerpt": "I'll be there!",
31 "created_at": "2012-03-24T09:53:35-05:00",
32 "updated_at": "2012-03-24T09:53:35-05:00",
33 "attachments": 0,
75e89e2 @georgeclaghorn Add a private flag to all privatables and a trashed flag to all trash…
georgeclaghorn authored
34 "private": false,
35 "trashed": false,
8eea848 @dhh Add Topics API
dhh authored
36 "last_updater": {
37 "id": 149087659,
38 "name": "Jason Fried"
39 },
40 "topicable": {
41 "id": 174886926,
42 "type": "CalendarEvent",
ca25498 @eileencodes Add `app_url` to json responses in documentation
eileencodes authored
43 "url": "https://basecamp.com/999999999/api/v1/projects/605816632/calendar_events/174886926.json",
44 "app_url": "https://basecamp.com/999999999/projects/605816632/calendar_events/174886926"
ac615b8 @georgeclaghorn Add support for archiving/activating topics
georgeclaghorn authored
45 },
46 "bucket": {
47 "id": 605816632,
48 "name": "BCX",
49 "type": "Project",
4778a52 @georgeclaghorn Merge branch 'master' into archiving-discussions
georgeclaghorn authored
50 "url": "https://basecamp.com/999999999/api/v1/projects/605816632.json",
51 "app_url": "https://basecamp.com/999999999/projects/605816632"
8eea848 @dhh Add Topics API
dhh authored
52 }
53 },
54 {
55 "id": 936075699,
56 "title": "Welcome!",
57 "excerpt": "Yeah, really, welcome!",
58 "created_at": "2012-03-24T09:53:35-05:00",
59 "updated_at": "2012-03-24T09:53:35-05:00",
60 "attachments": 1,
75e89e2 @georgeclaghorn Add a private flag to all privatables and a trashed flag to all trash…
georgeclaghorn authored
61 "private": false,
62 "trashed": false,
8eea848 @dhh Add Topics API
dhh authored
63 "last_updater": {
64 "id": 149087659,
65 "name": "Jason Fried"
66 },
67 "topicable": {
68 "id": 936075699,
69 "type": "Message",
ca25498 @eileencodes Add `app_url` to json responses in documentation
eileencodes authored
70 "url": "https://basecamp.com/999999999/api/v1/projects/605816632/messages/936075699.json",
71 "app_url": "https://basecamp.com/999999999/projects/605816632/messages/936075699"
ac615b8 @georgeclaghorn Add support for archiving/activating topics
georgeclaghorn authored
72 },
73 "bucket": {
74 "id": 605816632,
75 "name": "BCX",
76 "type": "Project",
4778a52 @georgeclaghorn Merge branch 'master' into archiving-discussions
georgeclaghorn authored
77 "url": "https://basecamp.com/999999999/api/v1/projects/605816632.json",
78 "app_url": "https://basecamp.com/999999999/projects/605816632"
8eea848 @dhh Add Topics API
dhh authored
79 }
80 }
81 ]
9b365b8 @dhh Clarifications
dhh authored
82 ```
83
427275f @georgeclaghorn Add support for sorting documents and topics
georgeclaghorn authored
84 For a topic:
85
86 * `title` is the original title of the topicable
87 * `excerpt` is from the latest comment on the topicable
88 * `last_updater` is the creator of the latest comment, or the creator of the
89 topicable if it has no comments
90
707c0e2 @georgeclaghorn Tidy up
georgeclaghorn authored
91 Buckets are only provided for topics that are not accessed via a project. For
92 example, topics returned from `GET /topics.json` will include their buckets,
93 but those returned from `GET /projects/1/topics.json` will not.
94
95 ### Pagination
96
97 We will return 50 topics per page. If the result set has 50 topics, it's your
98 responsibility to check the next page to see if there are any more topics --
99 you do this by adding `&page=2` to the query, then `&page=3` and so on.
100
101 ### Sorting
102
427275f @georgeclaghorn Add support for sorting documents and topics
georgeclaghorn authored
103 It's possible to change the order topics are returned in with the `sort`
104 parameter. Topics can be sorted by their latest update times using the
105 parameter values `newest` and `oldest`. The default sort is `newest`.
106
107 Sorting can be combined with pagination. To get the second page of topics
108 sorted by oldest first, request `/topics.json?page=2&sort=oldest`.
ac615b8 @georgeclaghorn Add support for archiving/activating topics
georgeclaghorn authored
109
110
111 Archive/activate a topic
112 ------------------------
113
114 * `PUT /projects/1/topics/1/archive.json` will archive the specified topic.
209e4bd @georgeclaghorn Wordsmith
georgeclaghorn authored
115 * `PUT /projects/1/topics/1/activate.json` will activate (reopen) the specified topic.
ac615b8 @georgeclaghorn Add support for archiving/activating topics
georgeclaghorn authored
116
117 No request body is necessary. In response, expect:
118
119 * `204 No Content` if archiving/activating is successful
120 * `403 Forbidden` if the topic's project is not active, or the authenticated user does not have permission
Something went wrong with that request. Please try again.