aboutsummaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorMatias Linares <matiaslina@gmail.com>2021-07-08 16:28:44 -0300
committerMatias Linares <matiaslina@gmail.com>2021-07-08 16:28:44 -0300
commitb4ed68b75285b022ba17c96c8da6da8d169a1d2b (patch)
treeb4af56ce11fc66fb40a89aa5e664593b44895291 /CONTRIBUTING.md
parent0977a6168362b4e811c66fbddb605ec44b9f1f58 (diff)
downloadperl6-matrix-client-b4ed68b75285b022ba17c96c8da6da8d169a1d2b.tar.gz
Add “how to add a new endpoint” to contributing filedocumentation
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md60
1 files changed, 60 insertions, 0 deletions
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
+ )
+ }
+
+ # ...
+}
+```