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.

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).

Credits

Thanks to PRAW for providing innumerable examples of Reddit API client code.