branch: elpa/fedi
commit 03b128fd103665f1bcce36c15726e9a98f728c19
Author: marty hiatt <martianhiatus [a t] riseup [d o t] net>
Commit: marty hiatt <martianhiatus [a t] riseup [d o t] net>
readme
---
readme.org | 19 +++++++------------
1 file changed, 7 insertions(+), 12 deletions(-)
diff --git a/readme.org b/readme.org
index 7ad62673b19..65682bd4ae7 100644
--- a/readme.org
+++ b/readme.org
@@ -2,24 +2,19 @@
A library to make writing clients for APIs easier.
-This is a WIP, with code being pulled over from my
[[https://codeberg.org/martianh/mastodon.el][mastodon.el]] to make it easy
-to write endpoint-hitting functions for JSON APIs. It will be cleaned up more,
-but it's already useable.
+It uses code from my
[[https://codeberg.org/martianh/mastodon.el][mastodon.el]] to make it easy to
write endpoint-hitting
+functions for JSON APIs.
-The macro =fedi-request= allows you to quickly create HTTP request commands to
-API endpoints, with parameters automatically constructed and sent as form data
or
-JSON payloads (for POST, PUT, DELETE, and probably PATCH).
+The example macro =fedi-request= allows you to quickly create HTTP request
+commands to API endpoints, with parameters automatically constructed and sent
+as form data or JSON payloads (for POST, PUT, DELETE, and probably PATCH). You
should write your own similar macro in your package. See my =lem.el= for an
working example. That way you can handle package-specific parameters such as
authentication.
Responses are checked with =fedi-http--triage=, and processed with
-=fedi-http--process-response=. If a response returns HTML, it is rendered
-with =shr=, otherwise the JSON is parsed and returned.
+=fedi-http--process-response=. If a response returns HTML (i.e. for a 404), it
+is rendered with =shr=, otherwise the JSON is parsed and returned.
Because of how =mastodon.el= works, there is also code for handling link
headers
in responses. Mastodon uses these for pagination in some cases. If your
service also does, you can handle them too.
-If you want to incorporate your service's authentication methods, you may find
-it easier to wrap the macro in another inside your own package and incorporate
-the auth work there, so you don't need to include it in every request.
-
For an example of using this library, see my
[[https://codeberg.org/martianh/lem][lem]] repo.
