doc/api/reference/directory.rst

   1 .. _directory-api:
   2
   3 Directory API
   4 =============
   5
   6 The Directory API can be used to discover podcasts.
   7
   8 TODO: report problems with podcasts (eg duplicates, missing data)
   9
  10
  11 Resources
  12 ---------
  13
  14 The Directory API defines the following resources ::
  15
  16     /search/podcasts
  17     /directory/toplist
  18     /directory/tags/latest
  19     /directory/tag/{tag}
  20     /user/{username}/suggestions
  21
  22
  23 Podcast Toplist
  24 ---------------
  25
  26 The podcast toplist ranks podcasts by their number of subscribers.
  27
  28
  29 Parameters
  30 ^^^^^^^^^^
  31
  32 * **lang**: a ISO 639-1 (two-letter) language code. If given, only podcasts in
  33   this language are returned. If omitted, no language restriction is made.
  34
  35 Request
  36 ^^^^^^^
  37
  38 Get the toplist ::
  39
  40     GET /directory/toplist{?lang:2}
  41     Content-Tpe: application/json
  42
  43
  44 Response
  45 ^^^^^^^^
  46
  47 The response contains a ``toplist`` member which has a list of
  48 :ref:`podcast-type` objects. The first entry in the list represents the highest
  49 ranking podcast in the toplist. If a ``lang`` parameter was included in the
  50 request, it is also included in the response. ::
  51
  52     200 OK
  53     Content-Tpe: application/json
  54
  55     {
  56         "toplist": [
  57             podcast1,
  58             podcast2,
  59             podcast3,
  60             ...
  61         ],
  62         "lang": "en"
  63     }
  64
  65
  66 Podcast Search
  67 --------------
  68
  69 Parameters
  70 ^^^^^^^^^^
  71
  72 * **q**: query string (mandatory)
  73
  74
  75 Request
  76 ^^^^^^^
  77
  78 The search query is provided as a GET parameter. ::
  79
  80     GET /search/podcasts{?q}
  81     Content-Tpe: application/json
  82
  83
  84 Responses
  85 ^^^^^^^^^
  86
  87 If the search could be performed, the search results (if any) are returned in
  88 the ``search`` member. The query is returned in the ``query`` member. ::
  89
  90     200 OK
  91     Content-Type: application/json
  92
  93     {
  94         "search": [
  95             podcast1,
  96             podcast2,
  97             ...
  98         ],
  99         "query": "query text"
 100     }
 101
 102
 103 If the search could not be performed, for example because the query was
 104 missing ::
 105
 106     400 Bad Request
 107     Content-Type: application/json
 108
 109     {
 110         "message": "parameter q missing",
 111         "errors": [
 112             {
 113                 field: "?q",
 114                 code: "parameter_missing"
 115             }
 116         ]
 117     }
 118
 119
 120 Example
 121 ^^^^^^^
 122
 123 Example::
 124
 125     GET /search/podcasts?q=linux
 126     Content-Tpe: application/json
 127
 128
 129     200 OK
 130     Content-Tpe: application/json
 131
 132     {
 133         "search": [
 134             { "url": "http://example.com/feed.rss", ...},
 135             { ... },
 136             ...
 137         ],
 138         "query": "linux"
 139     }
 140
 141
 142
 143 Latest Tags
 144 -----------
 145
 146 The "Latest Tags" endpoint returns *current* tags. Those are tags for which
 147 podcasts have recently published a new episode.
 148
 149 Parameters
 150 ^^^^^^^^^^
 151
 152 * **num**: number of tags to return (optional, default: 10)
 153
 154
 155 Request
 156 ^^^^^^^
 157
 158 The number of tags to return can be included in the request. ::
 159
 160     GET /directory/tags/latest{?num}
 161     Content-Tpe: application/json
 162
 163
 164 Reponse
 165 ^^^^^^^
 166
 167 In the ``tags`` member a list of :ref:`tag-type` objects is provided. ::
 168
 169     200 OK
 170     Content-Tpe: application/json
 171     Link: <https://api.gpodder.net/3/directory/tag/{label}>; rel="https://api.gpodder.net/3/relation/tag-podcasts"; title="Podcasts for tag {label}"
 172
 173     {
 174         "tags": [
 175             { "label": "Technology" },
 176             { ... },
 177             ...
 178         ]
 179     }
 180
 181 Clients can use the provided ``Link`` header and resolve the `URI template
 182 <http://tools.ietf.org/html/rfc6570>`_ to obtain the URL for retrieving the
 183 podcasts of a certain tag.
 184
 185
 186 Podcasts for Tag
 187 ----------------
 188
 189 Clients can retrieve podcasts for a given tag.
 190
 191
 192 Request
 193 ^^^^^^^
 194
 195 Request. ::
 196
 197     GET /directory/tag/{tag}
 198     Content-Tpe: application/json
 199
 200
 201 Response
 202 ^^^^^^^^
 203
 204 Response. ::
 205
 206     200 OK
 207     Content-Tpe: application/json
 208
 209     TODO: body
 210
 211
 212 Podcast Suggestions
 213 -------------------
 214
 215 Clients can retrieve suggested podcasts for the current user.
 216
 217
 218 Request
 219 ^^^^^^^
 220
 221 Request. ::
 222
 223     GET /user/{username}/suggestions
 224     Content-Tpe: application/json
 225
 226
 227
 228 Response
 229 ^^^^^^^^
 230
 231 The response contains a ``suggestions`` member which has a list of
 232 :ref:`podcast-type` objects. ::
 233
 234     200 OK
 235     Content-Tpe: application/json
 236
 237     {
 238         "suggestions": [
 239             { podcast1 },
 240             { podcast2 },
 241             ...
 242         ]
 243     }