doc/dev/couchdb-docs.rst

   1
   2 CouchDB Documents
   3 =================
   4
   5 This page describes the documents that are used in the CouchDB based backend of
   6 the gpodder.net webservice.
   7
   8 User
   9 ----
  10
  11 A registered (but probably not yet activated) user and all his devices.
  12
  13 Example Document ::
  14
  15     {
  16         username:         "stefan",
  17         email:            "stefan@gpodder.net",,
  18         password:         "asdf$asdfasdf$asdfsdfa",
  19         is_active:        False,
  20         registration_key: "ad18719239817389ad",
  21
  22         devices: [
  23             {
  24                 "_id":   "872348923987492834",
  25                 "user":  "stefan",
  26                 "id":    "n900",
  27                 "type":  "mobile",
  28                 "label": "N900"
  29             },
  30             { ... }
  31         ],
  32
  33         synchronized: [
  34             ["872348923987492834", "3498503485093495"],
  35             ["9384053405", "90548903458"]
  36         ]
  37     }
  38
  39
  40
  41 Podcast
  42 -------
  43
  44 If a Podcast does not belong to a group, it is a document on its own.  The
  45 "subscriber" field contains historical subscriber counts. The "tags" field
  46 contains all tags that are fetched in some automated way (ie not entered by a
  47 user).
  48
  49 A Podcast contains recent subscriber data in the "subscribers" property. To
  50 keep the Podcast objects small, subscriber data is periodically moved to the
  51 podcast's PodcastSubscriberData object.
  52
  53
  54 Example Document ::
  55
  56     {
  57         _id: "118913287192379173298"
  58         name: "Cool Podcast",
  59         feed_url: "http://podcast.com/mp3.xml",
  60         description: "..."
  61         subscribers: [{timestamp: "2010-09-01", subscriber_count: 120}, ... },
  62         related_podcasts: ["34059384598304850", "23480128409230482"],
  63         tags: {
  64             feed: [["technology", 50], ["news", 20]],
  65             delicious: [["technews", 10]]
  66         },
  67         publishers: ["stefan"],
  68         merged_ids: [ ...],
  69         language: "en",
  70         episodes: {
  71             19384038450938450983: { Episode },
  72             20928340283040234820. { Episode },
  73         },
  74         content_types: ["image", "audio"]
  75     }
  76
  77
  78 PodcastGroup
  79 ------------
  80
  81 Represents a group of podcast and contains all podcasts assigned to it.
  82 Once a Podcast is assigned to a group, its Podcast document in deleted
  83 and moved into the PodcastGroup.
  84
  85 Example Document ::
  86
  87     {
  88         _id: "9238409283402830480",
  89         oldid: 10,
  90         name: "Cool Podcast",
  91         podcasts: [
  92             {
  93                 id: "118913287192379173298",
  94                 name: "Cool Podcast",
  95                 group: "9238409283402830480",  # the _id of the group for
  96                                                # referring to it when the the
  97                                                # podcast is referred to separately
  98                 group_member_name: "MP3",             # required if Podcast is member of a group
  99                 feed_url: "http://podcast.com/mp3.xml",
 100                 description: "..."
 101                 subscribers: [[2010-09-01, 120], [2010-09-01, 130]],
 102                 related_podcasts: ["34059384598304850", "23480128409230482"],
 103                 tags: ["technology", "news"],
 104                 publishers: ["stefan"],
 105                 episodes: Episode-Dict
 106             },
 107             { ... }
 108         ],
 109     }
 110
 111
 112
 113 PodcastSubscriberData
 114 ---------------------
 115
 116 Contains the older subscriber data for a Podcast. This can be used to retrieve
 117 changes in the number of subscribers of a podcast.
 118
 119 Example Document ::
 120
 121     {
 122         podcast: "118913287192379173298",
 123         subscribers: [
 124             {timestamp: "2010-09-01", subscriber_count: 120},
 125             {timestamp: "2010-10-01", subscriber_count: 125},
 126             {timestamp: "2010-11-01", subscriber_count: 210},
 127         ],
 128     }
 129
 130
 131 Episode
 132 -------
 133
 134 An episode, in concept, belongs to a Podcast (not a PodcastGroup) but is a
 135 standalone document. It has optional support for multiple media files (eg Audio
 136 and PDF Show Notes). The fields listeners and recent_listeners are
 137 regularly updated with aggregated data to substitute queries based on time.
 138
 139 Example Document ::
 140
 141     {
 142         _id:    "19384038450938450983",
 143         title: "Cool Episode of Cool Podcast",
 144         podcast: "118913287192379173298",
 145         media_urls: ["http://podcast.com/episode1.mp3", "http://podcast.com/episode1.pdf"],
 146         released: "2010-09-20 12:00",
 147         tags: ["opensource", "technology"],
 148         merged_ids: ["908345083045", "29380423849"],
 149         media_types: ["audio"],
 150         listeners: [["2010-09-20", 20], ["2010-09-21", 15]],
 151         recent_listeners:  75,
 152         language: "en"
 153     }
 154
 155
 156 PodcastUserState
 157 ----------------
 158
 159 Contains everything that a User has done with a Podcast. The podcast is
 160 referenced by the "ref_url" which is the URL that was received via the API. It
 161 can be used in API responses so that the user receives exactly the same URL he
 162 has sent (the Podcast document could contain several URLs).
 163
 164 Example Document ::
 165
 166     {
 167         _id: "3893745983453948589345",
 168         user: "345983045035480345809",
 169         user_oldid: 4253,
 170         podcast: "118913287192379173298",
 171         ref_url: "http://example.com/podcast.xml",
 172         actions:
 173             [
 174                 {
 175                  action:    "subscribed",
 176                  timestamp: "2010-09-10",
 177                  device:    "872348923987492834"
 178                 },
 179                 {
 180                  action:    "unsubscribed",
 181                  timestamp: "2010-09-15",
 182                  device:    "872348923987492834"
 183                 }
 184             ],
 185         tags: ["technews"]
 186         settings: { ... }
 187     }
 188
 189
 190 Suggestions
 191 -----------
 192
 193 Contains the Podcast Suggestions and related meta-data (blacklist,
 194 suggestion-ratings) of a User. This is not places into PodcastUserState
 195 because the user did not yet interact with the Podcast directly.
 196
 197 Example Document ::
 198
 199     {
 200         user: "stefan",
 201         podcasts: [
 202             "119018023981293801823",
 203             "192840890284092834093"
 204         ],
 205         blacklist: [
 206             "456045698409586045860",
 207             "935937498573549739485"
 208         ],
 209         ratings: [
 210             { timestamp: "2010-09-13", rating: -1},
 211             { timestamp: "2010-09-15", rating:  1}
 212         ],
 213     }
 214
 215
 216 EpisodeUserState
 217 ----------------
 218
 219 A EpisodeUserState contains everything that a User has done with an Episode.
 220 The episode is referenced by the "ref_url" and "podcast_ref_url" which contain
 221 the URLs for the episode and the podcast, exactly as they have been received
 222 via the API. These values can also be used in API responses to refer to exactly
 223 the same URL as in the request (both Episode and Podcast documents can contain
 224 several URLs).
 225
 226 Example Document ::
 227
 228     {
 229         episode: "3893745983453948589345",
 230         podcast: "118913287192379173298",
 231         ref_url: "http://podcast.com/episode-1.mp3",
 232         podcast_ref_url: "http://podcast.com/mp3.xml",
 233         actions:
 234             [
 235                 {
 236                  action:    "download",
 237                  file:      "http://podcast.com/episode-1.mp3",
 238                  timestamp: "2010-09-10",
 239                  device:    "872348923987492834"
 240                 },
 241                 {
 242                  action:    "play",
 243                  file:      "http://podcast.com/episode-1.mp3",
 244                  timestamp: "2010-09-15",
 245                  device:    "872348923987492834"
 246                 }
 247             ],
 248         chapters: [
 249             {
 250                 from:          "02:10",
 251                 to:            "04:20",
 252                 advertisement: false,
 253                 label:         "interview",
 254             }
 255         ],
 256         settings: { ... }
 257     }
 258
 259
 260 Advertisement
 261 -------------
 262
 263 Contains an advertisement for a Podcast
 264
 265 Example Document ::
 266
 267     {
 268         user:    "stefan",
 269         podcast: "118913287192379173298",
 270         start:   "2010-09-01",
 271         end:     "2010-09-15"
 272     }
 273
 274
 275 Category
 276 --------
 277
 278 Represents a category within the Podcast Directory.
 279
 280 Example Document ::
 281
 282     {
 283         label:     "Technology",
 284         spellings: ["technology", "tech"],
 285         weight:    1200,
 286         updated:   "2010-09-28T08:38:03Z",
 287     }