use API::Discord::Endpoints;

unit package API::Discord;



head

API::Discord::JSONy - Role for objects that can be serialised to JSON


API::Discord::RESTy - Role for objects that can be sent/received over REST


API::Discord::HTTPResource - Role for objects that can be CRUD'd


This file defines the three roles listed above. They are all related to one
another but not necessarily all required at once.


This role defines the methods C<from-json> and C<to-json> that must be
implemented by the consuming class. Anything using this role can be sent to or
produced by RESTy.




role JSONy is export {
    #| Builds the object from a hash. The hash is made from the JSON, courtesy
    #| of Cro.
    method from-json (::?CLASS:U: $json) { ...  }

    #| Turns the object into a hash. from-json(to-json($object)) should return
    #| the same object (or at least an equivalent copy).
    method to-json returns Hash { ... }
}



This role defines C<send>, C<fetch>, and C<remove>, and is parameterised with a
base URL. It abstracts over the top of an HTTP client, so requires C<get>,
C<post>, C<put>, and C<delete> methods.


It is intended to be applied to L<Cro::HTTP::Client>, so the aforementioned
methods should match those.



role RESTy[$base-url] is export {
    has $.base-url = $base-url;

    multi method get ($uri, %args) {
        callwith("$.base-url$uri", %args);
    }
    multi method get ($uri, *%args) {
        callwith("$.base-url$uri", |%args);
    }
    multi method post ($uri, %args) {
        callwith("$.base-url$uri", %args);
    }
    multi method post ($uri, *%args) {
        callwith("$.base-url$uri", |%args);
    }
    multi method patch ($uri, %args) {
        callwith("$.base-url$uri", %args);
    }
    multi method patch ($uri, *%args) {
        callwith("$.base-url$uri", |%args);
    }
    multi method put ($uri, %args) {
        callwith("$.base-url$uri", %args);
    }
    multi method put ($uri, *%args) {
        callwith("$.base-url$uri", |%args);
    }
    multi method delete ($uri, %args) {
        callwith("$.base-url$uri", %args);
    }
    multi method delete ($uri, *%args) {
        callwith("$.base-url$uri", |%args);
    }

    #| Sends a JSONy object to the given endpoint. Updates if the object has an
    #| ID; creates if it does not.
    method send(Str $endpoint, JSONy:D $object) returns Promise {
        if $object.can('self-send') {
            return $object.self-send($endpoint, self)
        }
        # TODO: does anything generate data such that we need to re-fetch after
        # creation?
        use Data::Dump;
        my $body = $object.to-json;
        if $object.can('id') and $object.id {
            say "PATCH $endpoint " ~ Dump $body if %*ENV<API_DISCORD_DEBUG>;
            self.patch: $endpoint, :$body;
        }
        else {
            say "POST $endpoint " ~ Dump $body if %*ENV<API_DISCORD_DEBUG>;
            self.post: $endpoint, :$body;
        }
    }

    #| Sends a PUT but no data required. Useful to avoid creating whole classes
    #| just so they can self-send
    method touch(Str $endpoint) returns Promise {
        self.put: $endpoint, body => {};
    }

    #| Creates a JSONy object, given a full URL and the class.
    method fetch(Str $endpoint, JSONy:U $class, %data) returns Promise {
        start {
            my $b = await (await self.get($endpoint, %data)).body;
            $class.from-json($b);
        }
    }

    #| Deletes the thing with DELETE
    method remove(Str $endpoint) returns Promise {
        self.delete: $endpoint;
    }
}



Represents an object that can be discovered via some HTTP mechanism. The
consuming class is expected to have a hash called C<%.ENDPOINTS>, the purpose of
which is to provide a set of URL path templates that can be filled in by the
object being dealt with.


Endpoint handling is not yet fully implemented.


A gap in this process is that it does mean that in order to fetch an existing
object by ID, it is necessary to create an empty object containing that ID, and
then replace it with the response from C<read>, which will be a new object,
fully-populated.


Since all of the methods communicate via a RESTy object, it is currently
necessary that the class consuming HTTPResource also consumes JSONy.



role HTTPResource is export {
    #| Upload self, given a RESTy client. Returns a Promise that resolves to
    #| self. Not all resources can be created.
    method create(RESTy $rest) {
        my $endpoint = endpoint-for(self, 'create');
        $rest.send($endpoint, self);
    }

    #| Returns a Promise that resolves to a constructed object of this type. Use
    #| named parameters to pass in the data that the C<read> endpoint requires;
    #| usually an ID. Finally, pass in a connected RESTy object.
    method read(::?CLASS:U: %data, RESTy $rest) {
        my $endpoint = endpoint-for(self, 'read', |%data);
        $rest.fetch($endpoint, self, %data);
    }

    #| Updates the resource. Must have an ID already. Returns a Promise for the
    #| operation.
    multi method update(RESTy $rest) {
        my $endpoint = endpoint-for(self, 'update');
        $rest.send($endpoint, self);
    }

    #| Deletes the resource. Must have an ID already. Not all resources can be
    #| deleted. Returns a Promise.
    method delete(RESTy $rest) {
        my $endpoint = endpoint-for(self, 'delete');
        $rest.remove($endpoint);
    }
}


root

Message

Guild

React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


HTTPResource

NAME

DESCRIPTION

API::Discord::JSONy

API::Discord::RESTy[$base-url]

API::Discord::HTTPResource