branch: elpa/fedi
commit 3f0883c8d45e1a6b9b01052291a792965bd16219
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 | 15 ++++++++++++---
1 file changed, 12 insertions(+), 3 deletions(-)
diff --git a/readme.org b/readme.org
index ab1c55e8a5d..7e0525d418d 100644
--- a/readme.org
+++ b/readme.org
@@ -2,10 +2,19 @@
A library to make writing clients for APIs easier.
-This is a WIP mess, with code taken from mastodon.el. It will be cleaned up,
and made less convoluted, but it's already useable.
+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.
-The macro =fedi-request= allows you to quickly create HTTP request commands to
endpoints provided, with parameters sent as form data or JSON payloads (for
POST, PUT, probably PATCH).
+The macro =fedi-request= allows you to quickly create HTTP request commands to
endpoints provided, with parameters automatically constructed and sent as form
data or JSON payloads (for POST, PUT, DELETE, and probably PATCH).
-If you want to incorporate your service's authentication methods, you may find
it easier to copy the macro and incorporate the auth work into it, so you don't
need to include it in every request.
+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 pased 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 des, 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.
