package reddit_api_kernel
OCaml types for Reddit's API
Install
Dune Dependency
Authors
Maintainers
Sources
0.1.1.tar.gz
md5=a1d58d3db30d748673393d5b97f11d44
sha512=32d1977dbbb9ecb8da3eb5e264927a82cc2efa02f2f6838d54321475c2d76171feeff70d95f99b37fbaf7c13c6158abe08422f85da2cf332c50cb413f9154fa0
Description
Published: 31 Dec 2020
README
reddit_api
is a set OCaml client libraries for Reddit's API.
reddit_api_kernel
provides:
- Types for representing Reddit's API parameters and responses
- Functions for building HTTP requests and handling the associated responses for Reddit's API endpoints.
reddit_api_async
provides a client for sending these requests to Reddit and some utilities for common usage patterns. It handles authentication and Reddit's rate-limiting headers.
Documentation
Here. I recommend the Reddit_api_kernel.Api
and Reddit_api_async.Connection
modules as entry points.
Example
let print_links credentials =
let connection = Connection.create credentials ~user_agent:"Link printer" in
let subreddit =
Subreddit_name.combine (List.map ~f:Subreddit_name.of_string [ "ocaml"; "redditdev" ])
in
let%bind link_listing =
Connection.call_exn connection (Api.top ~since:Year ~subreddit ())
in
let links = Listing.children link_listing in
List.iter links ~f:(fun link ->
print_s
[%sexp
{ title : string = Thing.Link.title link
; url : string option = Option.map (Thing.Link.url link) ~f:Uri.to_string
; author : Username.t option = Thing.Link.author link
; score : int = Thing.Link.score link
}]);
return ()
Goals and non-goals
Goals
- Provide a typed interface to Reddit's API endpoints and responses.
Encode knowledge, documented or otherwise, about correct usage of the API via the type system.
- Don't raise exceptions if Reddit is behaving "as expected."
- Express corner cases in response types. For example, are there surprising cases where a field might not be present? Make the field optional instead of making each user discover this on their own.
- Handle common Reddit server issues such as 503 errors automatically, or else warn about them via the response type.
Provide workarounds when we get the above wrong:
- A
?param_list_override:((string * string list) list -> (string * string list) list)
option on each API endpoint that allows the HTTP parameters to be manipulated directly. - A
Connection.call_raw
function that allows users to access HTTP responses directly.
- A
Non-goals
Be perfect
- Reddit's API is not very well documented. Determining which inputs and outputs are legal is largely a matter of trial and error. At any given time, it's likely that we allow some invalid combination of inputs, or forbid a valid combination, or fail to handle some valid response.
Express "unexpected" Reddit behavior in the type system.
- If we get something from Reddit that we don't understand, we'll just raise. We don't make every function return a
(_, [`couldn't_parse_response]) Result.t)
.
- If we get something from Reddit that we don't understand, we'll just raise. We don't make every function return a
Credits
Thanks to PRAW for providing innumerable examples of Reddit API client code.
Dependencies (4)
-
ezjsonm
>= "1.0"
-
core_kernel
>= "v0.14.0" & < "v0.16.0"
-
cohttp
>= "2.5.4"
-
dune
>= "2.5"
Dev Dependencies (1)
-
odoc
with-doc
Used by (1)
-
reddit_api_async
= "0.1.1"
Conflicts
None
sectionYPositions = computeSectionYPositions($el), 10)"
x-init="setTimeout(() => sectionYPositions = computeSectionYPositions($el), 10)"
>
On This Page