The Podcast Index API, https://podcastindex-org.github.io/docs-api/, as request maps and model maps.
A request is a map of :method, :url and :headers that any HTTP client can send, with the authentication for the time it's given. A response reads into data shaped like the feed model, so a feed or an episode from the index has the same keys as one parsed from RSS, and what only the index knows is in the index namespace.
The key and the secret never leave your process. Nothing here reads a clock but the functions that send.
The Podcast Index API, https://podcastindex-org.github.io/docs-api/, as request maps and model maps. A request is a map of :method, :url and :headers that any HTTP client can send, with the authentication for the time it's given. A response reads into data shaped like the feed model, so a feed or an episode from the index has the same keys as one parsed from RSS, and what only the index knows is in the index namespace. The key and the secret never leave your process. Nothing here reads a clock but the functions that send.
The root of the URLs of the API, which the paths of calls are below, unless the options give the root of another service with the same API as :base-url.
The root of the URLs of the API, which the paths of calls are below, unless the options give the root of another service with the same API as :base-url.
The calls of paths that take a JSON body in a POST rather than a query: :podcasts/batch-by-guid takes a vector of feed guids, and :value/batch-by-episode-guid a map of a feed guid to its episode guids.
The calls of paths that take a JSON body in a POST rather than a query: :podcasts/batch-by-guid takes a vector of feed guids, and :value/batch-by-episode-guid a map of a feed guid to its episode guids.
(call! credentials call)(call! credentials call params)(call! credentials call params {:keys [send] :or {send client/send!} :as opts})Send call for credentials with its params, when it takes any, and
read the answer, in ClojureScript in a promise. The opts are these:
In a browser, the call works only where the CORS policy of the API allows it, or through a :send that goes through your own server.
Send `call` for `credentials` with its `params`, when it takes any, and read the answer, in ClojureScript in a promise. The `opts` are these: - :base-url, as request takes it - :auth-date, as request takes it, the time of :now-fn by default - :now-fn, the clock, time/now by default - :send, the function that sends the request, client/send! by default In a browser, the call works only where the CORS policy of the API allows it, or through a :send that goes through your own server.
The categories of the Podcast Index by id, from categories.json of the podcast namespace. They are the words of the categories of Apple Podcasts: Society & Culture is Society and Culture here.
The call :categories/list gives the list as the index has it now.
The categories of the Podcast Index by id, from categories.json of the podcast namespace. They are the words of the categories of Apple Podcasts: Society & Culture is Society and Culture here. The call :categories/list gives the list as the index has it now.
(category-filter category)(category-filter category opts)The value of the parameters cat and notcat for category, by the
:categories of opts, or else the categories table. It's nil for no
category.
The category is a name or an id of a category, or a collection of
them. A name can hold several names with commas or ampersands between
them, so a name of Apple Podcasts such as Society & Culture reads as its
two categories. The case of a name doesn't count, and a space reads as
a hyphen where the index has one.
For a name that it doesn't know, the index gives the whole chart and no error. So this throws for such a name.
The value of the parameters cat and notcat for `category`, by the :categories of `opts`, or else the categories table. It's nil for no category. The `category` is a name or an id of a category, or a collection of them. A name can hold several names with commas or ampersands between them, so a name of Apple Podcasts such as Society & Culture reads as its two categories. The case of a name doesn't count, and a space reads as a hyphen where the index has one. For a name that it doesn't know, the index gives the whole chart and no error. So this throws for such a name.
(episode->model e)The episode object e of the index as an item map. It has the keys of
a parsed item where the index has the same information, keys in the
index namespace for the rest, and the original as :index/raw.
The episode object `e` of the index as an item map. It has the keys of a parsed item where the index has the same information, keys in the index namespace for the rest, and the original as :index/raw.
(fetch-remote-item! credentials item)(fetch-remote-item! credentials
item
{:keys [send] :or {send client/send!} :as opts})Fetch what the remote item points at for credentials, with the
opts of fetch-remote-value!, in ClojureScript in a promise.
It's a map of the :feed and the :episode in the shape of the model, or nil when the index knows neither. The requests for the episode and the feed go at once. When neither gets an answer, it's a map with a :directory/source-failed diagnostic under :error.
Fetch what the remote `item` points at for `credentials`, with the `opts` of fetch-remote-value!, in ClojureScript in a promise. It's a map of the :feed and the :episode in the shape of the model, or nil when the index knows neither. The requests for the episode and the feed go at once. When neither gets an answer, it's a map with a :directory/source-failed diagnostic under :error.
(fetch-remote-value! credentials remote-item)(fetch-remote-value! credentials
remote-item
{:keys [send] :or {send client/send!} :as opts})Fetch the value block that remote-item of a time split points at for
credentials, with the opts below. It gives the block, nil when the
index has none, or a map with a diagnostic under :error, in
ClojureScript in a promise.
The requests go one by one, for the block of the item first, until one
answers with a block or fails. An answer of 400 or 404 says that the
index doesn't know the guid. Nothing that the network or the server
does throws. The opts are those of call!, and the :allow-pred,
:timeout-seconds, :max-bytes and :user-agent that http/try-send! takes.
Fetch the value block that `remote-item` of a time split points at for `credentials`, with the `opts` below. It gives the block, nil when the index has none, or a map with a diagnostic under :error, in ClojureScript in a promise. The requests go one by one, for the block of the item first, until one answers with a block or fails. An answer of 400 or 404 says that the index doesn't know the guid. Nothing that the network or the server does throws. The `opts` are those of call!, and the :allow-pred, :timeout-seconds, :max-bytes and :user-agent that http/try-send! takes.
The path of each call of the API by a keyword, as its OpenAPI description lists them. Each takes its parameters as a query, but those of batch-calls.
The path of each call of the API by a keyword, as its OpenAPI description lists them. Each takes its parameters as a query, but those of batch-calls.
(remote-item-requests credentials
{:keys [feed-guid item-guid] :as remote-item}
opts)The requests to try in order for remote-item, with credentials and
opts as request takes them. The episode comes first, when it's named,
and then the feed.
The remote-item is a podroll, publisher, list or time-split entry with
a :feed-guid and perhaps an :item-guid.
The requests to try in order for `remote-item`, with `credentials` and `opts` as request takes them. The episode comes first, when it's named, and then the feed. The `remote-item` is a podroll, publisher, list or time-split entry with a :feed-guid and perhaps an :item-guid.
(remote-value-requests credentials
{:keys [feed-guid item-guid] :as remote-item}
opts)The requests to try in order for the value block that remote-item of
a time split points at, with credentials and opts as request takes
them.
The block of the item comes first, when the remote item names one, and then that of the feed.
The requests to try in order for the value block that `remote-item` of a time split points at, with `credentials` and `opts` as request takes them. The block of the item comes first, when the remote item names one, and then that of the feed.
(request credentials call params {:keys [auth-date] :as opts})The request map for call, a key of paths, with params, signed with
credentials at the :auth-date of opts.
The params are the query of the call, or the JSON body of one of batch-calls, which is a POST. The credentials are a :key and a :secret, and they can give a :user-agent. The :auth-date is in Unix seconds. The API takes a date within a few minutes of its own clock, so read the clock for it.
The request goes to base-url, or to the :base-url of opts.
The request map for `call`, a key of paths, with `params`, signed with `credentials` at the :auth-date of `opts`. The params are the query of the call, or the JSON body of one of batch-calls, which is a POST. The credentials are a :key and a :secret, and they can give a :user-agent. The :auth-date is in Unix seconds. The API takes a date within a few minutes of its own clock, so read the clock for it. The request goes to base-url, or to the :base-url of `opts`.
(response body)The data in the JSON body of an API response:
The data in the JSON `body` of an API response: - :status, as a boolean - :description, :count and :query, as given - feeds as :feed or :feeds, and episodes as :episode, :items or :live-items, in the shape of the model - a value block as :value, and the blocks of a batch as :values, a map of the id of each episode, its feed guid and its guid, to its block - the whole parsed body as :raw
(sender credentials)(sender credentials
{:keys [send now-fn] :or {send client/send! now-fn time/now} :as opts})A function to give as :send, which signs each request to the Podcast
Index with credentials and sends it with the :send of opts.
Give it to the proxy on your server, e.g. (proxy/handler {:send (sender
credentials)}), so that the secret stays there, and give the page
credentials without a :secret. The signature replaces any that the
request has, at the time of the :now-fn of opts. A request to another
URL than those below base-url, or the :base-url of opts, goes as it
is. The :send is client/send! by default.
A function to give as :send, which signs each request to the Podcast
Index with `credentials` and sends it with the :send of `opts`.
Give it to the proxy on your server, e.g. (proxy/handler {:send (sender
credentials)}), so that the secret stays there, and give the page
credentials without a :secret. The signature replaces any that the
request has, at the time of the :now-fn of `opts`. A request to another
URL than those below base-url, or the :base-url of `opts`, goes as it
is. The :send is client/send! by default.(try-response body)The data in the JSON body of an API response, as response reads it,
or nil when it doesn't read.
The data in the JSON `body` of an API response, as response reads it, or nil when it doesn't read.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |