Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/raku-community-modules/www

No-nonsense simple HTTPS client with JSON decoder
https://github.com/raku-community-modules/www

raku

Last synced: 3 months ago
JSON representation

No-nonsense simple HTTPS client with JSON decoder

Awesome Lists containing this project

README 

        
![Logo](logotype/logo_32x32.png) | ![Test](https://github.com/raku-community-modules/WWW/workflows/Test/badge.svg)[![Test-create and publish Docker images](https://github.com/raku-community-modules/WWW/actions/workflows/test-upload-ghcr.yaml/badge.svg)](https://github.com/raku-community-modules/WWW/actions/workflows/test-upload-ghcr.yaml)



# NAME



WWW - No-nonsense, simple HTTPS client with JSON decoder



# SYNOPSIS



```raku

use WWW;



# Just GET content (will return Failure on failure):

say get 'https://httpbin.org/get?foo=42&bar=x', :SomeHeader;



# GET and decode received data as JSON:

say jget('https://httpbin.org/get?foo=42&bar=x');



# POST content (query args are OK; pass form as named args)

say post 'https://httpbin.org/post?foo=42&bar=x', :some, :42args;



# And if you need headers, pass them inside a positional Hash:

say post 'https://httpbin.org/post?foo=42&bar=x', %(:Some),

    :some, :42args;



# Same POST as above + decode response as JSON

say jpost('https://httpbin.org/post', :some);



# Also can post() or jpost() POST body directly as Str:D; headers passed as named args:

say jpost(

    "http://httpbin.org/post",

    to-json({:42a, :foo}),

    :Authorization

).;

```



Import more HTTP methods using `:extras`



```raku

use WWW :extras;



say jdelete 'https://httpbin.org/delete';

say jput    'https://httpbin.org/put';

```



# DESCRIPTION



Exports a handful of routines to fetch data from online resources

using HTTP verbs and optionally decode the responses as JSON.



The module will set the `User-Agent` header to `Rakudo WWW`, unless you specify

that header.



# INSTALLATION



On some operating systems you'll need `libssl` installed:



```bash

sudo apt-get install libssl-dev

```



Then just install the module with the module manager:



```bash

zef install WWW

```



# TESTING



To run the full test suite, set `ONLINE_TESTING` environmental variable to `1`



```bash

ONLINE_TESTING=1 zef install WWW

```



# EXPORTED ROUTINES



## `:DEFAULT` export tag



These routines get exported by default:



### `get`



```raku

sub get($url where URI:D|Str:D, *%headers --> Str:D);



say get 'https://httpbin.org/get?foo=42&bar=x';

```



Takes either a `Str` or a [URI](https://modules.raku.org/dist/URI).

Returns `Failure` if request fails or does not return a successful HTTP code.

Returns `Str` with the data on success. Takes headers as named arguments.



### `jget`



```raku

say jget 'https://httpbin.org/get?foo=42&bar=x';

```



Same as `get()` except will also decode the response as JSON and return

resultant data structure.



### `post`



```raku

multi post($url where URI:D|Str:D, *%form --> Str:D);

multi post($url where URI:D|Str:D, %headers, *%form --> Str:D);

multi post($url where URI:D|Str:D, Str:D $form-body, *%headers --> Str:D);



say post 'https://httpbin.org/post?meow=moo', :72foo, :bar<♵>;

say post 'https://httpbin.org/post?meow=moo',

    %(Content-type => 'application/json'), :72foo, :bar<♵>;

```



Takes either a `Str` or a [URI](https://modules.raku.org/dist/URI), followed

by an optional `Hash` with HTTP headers to send. Form POST parameters can be

included as named arguments. It's fine to also include query arguments in the

URL itself. Returns `Failure` if request fails or does not return a successful

HTTP code. Returns `Str` with the data on success.



To send POST body directly, pass it as Str:D positional arg. In this calling

form, the headers are sent as named args.



### `jpost`



```raku

multi jpost($url where URI:D|Str:D, *%form);

multi jpost($url where URI:D|Str:D, %headers, *%form);

multi jpost($url where URI:D|Str:D, Str:D $form-body, *%headers);



say jpost 'https://httpbin.org/post?meow=moo', :72foo, :bar<♵>;

say jpost 'https://httpbin.org/post?meow=moo',

    %(Content-type => 'application/json'), :72foo, :bar<♵>;

```



Same as `post()` except will also decode the response as JSON and return

resultant data structure.



### `head`



```raku

say head 'https://httpbin.org/get?foo=42&bar=x';

```



Same as `get`, except it does not actually download the content, just the head.



## `:extras` Export Tag



These routines get exported *in addition to* the `:DEFAULT` exports, when

`:extras` export tag is requested:



```raku

use WWW :extras;

```



### `put`



```raku

multi put($url where URI:D|Str:D, *%form --> Str:D);

multi put($url where URI:D|Str:D, %headers, *%form --> Str:D);

multi put($url where URI:D|Str:D, Str:D $form-body, *%headers --> Str:D);



say put 'https://httpbin.org/put?meow=moo', :72foo, :bar<♵>;

say put 'https://httpbin.org/put?meow=moo',

    %(Content-type => 'application/json'), :72foo, :bar<♵>;

```



Takes either a `Str` or a [URI](https://modules.raku.org/dist/URI), followed

by an optional `Hash` with HTTP headers to send. Form PUT parameters can be

included as named arguments. It's fine to also include query arguments in the

URL itself. Returns `Failure` if request fails or does not return a successful

HTTP code. Returns `Str` with the data on success.



To send PUT body directly, pass it as Str:D positional arg. In this calling

form, the headers are sent as named args.



### `jput`



```raku

multi jput($url where URI:D|Str:D, *%form --> Str:D);

multi jput($url where URI:D|Str:D, %headers, *%form --> Str:D);

multi jput($url where URI:D|Str:D, Str:D $form-body, *%headers --> Str:D);



say jput 'https://httpbin.org/put?meow=moo', :72foo, :bar<♵>;

say jput 'https://httpbin.org/put?meow=moo',

    %(Content-type => 'application/json'), :72foo, :bar<♵>;

```



Same as `put()` except will also decode the response as JSON and return

resultant data structure.



### `delete`



```raku

sub delete($url where URI:D|Str:D, *%headers --> Str:D);



say delete 'https://httpbin.org/get?foo=42&bar=x';

```



Performs HTTP `DELETE` request.

Takes either a `Str` or a [URI](https://modules.raku.org/dist/URI).

Returns `Failure` if request fails or does not return a successful HTTP code.

Returns `Str` with the data on success; if response for a `204 No Content`,

returns an empty string. Takes headers as named arguments.



### `jdelete`



```raku

say jdelete 'https://httpbin.org/get?foo=42&bar=x';

```



Same as `delete()` except will also decode the response as JSON and return

resultant data structure.



You probably want to use `delete()` instead, as `DELETE` requests can get

return no content, causing JSON parse failures.



# LIMITATIONS



Due to nuances of upstream code, currently any non-RFC-conformant URL will

be rejected; you have to ensure it's proper manually. Patches welcome.



# SEE ALSO



- [`LWP::Simple`](https://raku.land/zef:raku-community-modules/LWP::Simple)

- [`HTTP::UserAgent`](https://raku.land/github:sergot/HTTP::UserAgent)



----



#### REPOSITORY



Fork this module on GitHub:

https://github.com/raku-community-modules/WWW



#### BUGS



To report bugs or request features, please use

https://github.com/raku-community-modules/WWW/issues



#### ORIGINAL AUTHOR



Zoffix Znet (http://perl6.party/)



Now maintained by the Raku community as part of the [Raku community modules](https://github.com/raku-community-modules)



#### LICENSE



You can use and distribute this module under the terms of the

The Artistic License 2.0. See the `LICENSE` file included in this

distribution for complete details.



The `META6.json` file of this distribution may be distributed and modified

without restrictions or attribution.