From b4ed68b75285b022ba17c96c8da6da8d169a1d2b Mon Sep 17 00:00:00 2001
From: Matias Linares <matiaslina@gmail.com>
Date: Thu, 8 Jul 2021 16:28:44 -0300
Subject: Add “how to add a new endpoint” to contributing file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CONTRIBUTING.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

(limited to 'CONTRIBUTING.md')

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e5f0590..de342c9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -76,3 +76,63 @@ You must increment this variable on use. A
 # How do I...
 
 ## Add a new endpoint?
+
+As an example, I will be using the [ban](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-rooms-roomid-ban) endpoint.
+
+We know from the specification that:
+
+- It's a `POST`.
+- The endpoint is `/_matrix/client/r0/rooms/{roomId}/ban`.
+- Requires authentication.
+- Has two required parameters.
+  + `room_id`: It's on the URL.
+  + `user_id`: This is the user that we wan't to ban.
+- Has an optionas parameter: the `reason`.
+
+With this information we can make the signature of the method on the
+`Matrix::Client::Room` class.
+
+```raku
+method ban(Str $user-id, $reason = "") {
+```
+
+We don't need to specify the `room_id` because it's already an attribute of the class.
+
+Because the Room class `does Matrix::Client::Requester`, we have all the
+methods to make an http request. This also handles authentication.
+
+We'll call the `$.post` method with the endpoint as it's first parameter
+and the rest of the named parameters will be the `user_id` and the `reason`. All
+named parameters will be passed into the body of the json.
+
+The `Matrix::Client::Room` class already prepends the first part of the endpoint (
+`/_matrix/client/r0/rooms/{roomId}`) so we only specify what's after the `{roomId}` part
+of the url.
+
+```raku
+    $.post('/ban', :user_id($user-id), :$reason)
+```
+
+And done :)
+
+After that, you should add the `ban` method also to the `Matrix::Client` class
+instantiating a `Matrix::Client::Room` with a `$room-id` argument.
+
+```raku
+class Matrix::Client does Matrix::Client::Requester {
+    # ...
+
+    method ban(Str $room-id, $user-id, :$reason) {
+        Matrix::Client::Room.new(
+            :id($room-id),
+            :access-token(self.access-token),
+            :home-server(self.home-server)
+        ).ban(
+            $user-id,
+            :$reason
+        )
+    }
+
+    # ...
+}
+```
-- 
cgit v1.2.3-70-g09d2