diff --git a/README.md b/README.md index 3ac752b..3d584f5 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,44 @@ - -# Roblox Requests 0.2.0 +# Roblox Requests **Roblox Requests** brings user-friendly HTTP to Roblox with no need for the manual labor of HttpService. With Requests you can send robust, human-readable HTTP requests without ever having to deal with the underlying HttpService. No more manual query strings or encoding POST data. -## Roblox Requests Features - -- Sessions with cookie persistence, base URLs/headers -- Automatic query string building -- Automatic JSON body encoding -- Builtin Response object and JSON decoding -- Domain based Key/Value cookies -- Multipart form building including file encoding and upload -- Global ratelimiting with per-session config options - ---- - -An example of what you can do with Requests: +#### The Power of Roblox Requests: ```lua -local http = require(game.ReplicatedStorage.http) +local r = http.get("https://api.github.com/orgs/Roblox/repos") -local r = http.post("https://httpbin.org/post", { - query = {arg="value"}, - data = {this="json"} -}) +print(r.status_code, r.message) +-- 200 OK -print(r.content_type, - r:json().url) +repos = r:json() +print(#repos) +-- 30 --- output: +print(r.content_type) -- application/json --- https://httpbin.org/post?arg=value +print(r.encoding) +-- utf-8 +print(r.headers["x-ratelimit-remaining"]) +-- 59 ``` -See [similar code with HttpService.](https://gist.github.com/jpatrickdill/8fe2a82c47c1bdf679eb1a1c5f07d7a0) +Roblox Requests will bring simple support for all internet resources to your game. + +## Features -Requests' powerful API allows you to send HTTP/1.1 requests without the need of manual labor. You'll never -have to add query strings to URLs or encode your POST data again. +- Sessions with Cookie Persistence +- Default Headers, URL prefixes +- Automatic Query Strings +- JSON Body Encoding, JSON Response Decoding +- Elegant Key/Value Cookies + - Domain/Path filters +- Multipart File Encoding and Upload +- Global/Per-Session Ratelimiting -## [Documentation](https://jpatrickdill.github.io/roblox-requests/guide/installation/) +Roblox Requests was inspired by the well known [Python Requests](https://2.python-requests.org/en/master/) library. [In this documentation](https://jpatrickdill.github.io/roblox-requests/guide/installation/) you'll find step-by-step instructions to get the most out of Roblox Requests. diff --git a/default.project.json b/default.project.json new file mode 100644 index 0000000..2981b93 --- /dev/null +++ b/default.project.json @@ -0,0 +1,14 @@ +{ + "name": "roblox-requests", + "tree": { + "$className": "DataModel", + + "ReplicatedStorage": { + "$className": "ReplicatedStorage", + + "http": { + "$path": "http" + } + } + } +} \ No newline at end of file diff --git a/docs/api-reference.md b/docs/api-reference.md index 59af28c..83d16e0 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -84,11 +84,11 @@ will not block the current thread. - **request** (Request) - Request that generated this response - **url** (string) - Requests' URL - **method** (string) - Request's HTTP method -- **success** (bool) - `true` if response was successful -- **code** (number) - Status code of reponse +- **ok** (bool) - `true` if response has OK status code (200 \<= code \< 300) +- **status_code** (number) - Status code of reponse - **message** (string) - Status message of response - **headers** (dictionary) - Headers sent in response -- **content** (string) - Response body +- **text** (string) - Response body - **cookies** (CookieJar) - New cookies sent in this response ### Response:json diff --git a/docs/changes.md b/docs/changes.md deleted file mode 100644 index 2f1924f..0000000 --- a/docs/changes.md +++ /dev/null @@ -1,26 +0,0 @@ -# {{ version }} Release Notes - -Here you'll find a list of changes in this release, along with a list of what's to come. - -## Additions - -### Global Rate-Limiting - -Requests are rate-limited using a sliding window. -Default setting is 250 requests / 30 seconds, but can be changed via `http.set_ratelimit`. -Individual session rate-limits can also be with `Session:set_ratelimit`. - -## Changes - -- Reworked FormData class - - Fields are now passed in a dictionary - - `:AddField()` method used for both text and file fields - - New `http.File` class for files - -- Reworked CookieJars - - Cookies can now use domain and path qualifiers - - new `Cookie` class used internally - - `CookieJar:insert(name, value, opts)` for adding new cookies - -!!! warning - Backwards-compatibility is NOT guaranteed before version 1.0. \ No newline at end of file diff --git a/docs/guide/quickstart.md b/docs/guide/quickstart.md index 8e32229..41f2b71 100644 --- a/docs/guide/quickstart.md +++ b/docs/guide/quickstart.md @@ -88,7 +88,7 @@ print(r.headers["Last-Modified"]) -- Wed, 08 Oct 2014 23:28:44 GMT ``` -This dictionary, however, is special. HTTP headers are case-insensitive, so you can access them however you like: +HTTP headers are case-insensitive, so you can access them however you like: ```lua print(r.headers["Last-Modified"]) diff --git a/docs/img/with.gif b/docs/img/with.gif new file mode 100644 index 0000000..71aab24 Binary files /dev/null and b/docs/img/with.gif differ diff --git a/docs/img/without.gif b/docs/img/without.gif new file mode 100644 index 0000000..c4ed911 Binary files /dev/null and b/docs/img/without.gif differ diff --git a/docs/index.md b/docs/index.md index 8e66200..7b1f0da 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,39 +1,43 @@ -# Roblox Requests {{ version }} +# Roblox Requests **Roblox Requests** brings user-friendly HTTP to Roblox with no need for the manual labor of HttpService. ---- +With Requests you can send robust, human-readable HTTP requests without ever having to deal with the underlying HttpService. +No more manual query strings or encoding POST data. -An example of what you can do with Requests: +#### The Power of Roblox Requests: ```lua -local http = require(game.ReplicatedStorage.http) +local r = http.get("https://api.github.com/orgs/Roblox/repos") -local r = http.post("https://httpbin.org/post", { query = {arg="value"}, - data = {key="value"} }) +print(r.status_code, r.message) +-- 200 OK -print(r.content_type, - r:json().url) +repos = r:json() +print(#repos) +-- 30 --- output: +print(r.content_type) -- application/json --- https://httpbin.org/post?arg=value +print(r.encoding) +-- utf-8 +print(r.headers["x-ratelimit-remaining"]) +-- 59 ``` -See [similar code with HttpService.](https://gist.github.com/jpatrickdill/8fe2a82c47c1bdf679eb1a1c5f07d7a0) +Roblox Requests will bring simple support for all internet resources to your game. -Requests' powerful API allows you to send HTTP/1.1 requests without the need of manual labor. You'll never -have to add query strings to URLs or encode your POST data again. +## Features -### Roblox Requests Features +- Sessions with Cookie Persistence +- Default Headers, URL prefixes +- Automatic Query Strings +- JSON Body Encoding, JSON Response Decoding +- Elegant Key/Value Cookies + - Domain/Path filters +- Multipart File Encoding and Upload +- Global/Per-Session Ratelimiting -- Sessions with cookie persistence, base URLs/headers -- Automatic query string building -- Automatic JSON body encoding -- Builtin Response object and JSON decoding -- Domain based Key/Value cookies -- Multipart form building including file encoding and upload -- Global ratelimiting with per-session config options Roblox Requests was inspired by the well known [Python Requests](https://2.python-requests.org/en/master/) library. diff --git a/example.lua b/example.lua new file mode 100644 index 0000000..8967959 --- /dev/null +++ b/example.lua @@ -0,0 +1,8 @@ +local HttpService = game:GetService("HttpService") + +local body = HttpService:JSONEncode({cookies = "milk"}) +local r = HttpService:RequestAsync({Url = "https://httpbin.org/put", Method="PUT", Body=body}) + +if r.Success then + data = HttpService:JSONDecode(r.Body) +end \ No newline at end of file diff --git a/http/init.lua b/http/init.lua index 96f4e95..a0dcd38 100644 --- a/http/init.lua +++ b/http/init.lua @@ -14,7 +14,7 @@ local RateLimiter = require(Src.ratelimit) local http = {} -http.VERSION = "0.2.0" +http.VERSION = "0.2.1" http.Request = Request.new http.Session = Session.new diff --git a/http/src/response.lua b/http/src/response.lua index 2e79a82..442e4ef 100644 --- a/http/src/response.lua +++ b/http/src/response.lua @@ -26,14 +26,25 @@ function Response.new(req, resp, rt) self.method = req.method -- response data - self.success = resp.Success - self.code = resp.StatusCode + self.code = resp.StatusCode -- deprecated + self.status_code = resp.StatusCode + + self.success = resp.Success -- deprecated + self.ok = self.status_code >= 200 and self.status_code < 300 + self.message = resp.StatusMessage self.headers = CaseInsensitive(resp.Headers) - self.content = resp.Body + + self.content = resp.Body -- deprecated + self.text = resp.Body + -- additional metadata for quick access - self.content_type = self.headers["content-type"] + local type_encoding = self.headers["content-type"]:split(";") + self.content_type = type_encoding[1] + self.encoding = (type_encoding[2] and type_encoding[2]:split("=")[2]) or "" -- or "utf-8" + + self.content_length = self.headers["content-length"] or #self.content -- cookies @@ -47,7 +58,7 @@ function Response.new(req, resp, rt) end function Response:__tostring() - return self.content + return self.text end function Response:json() diff --git a/mkdocs.yml b/mkdocs.yml index 67bd15a..169f0c9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,7 +18,6 @@ plugins: nav: - Home: index.md - - Release Notes: changes.md - Guide: - Installation: guide/installation.md - Quickstart: guide/quickstart.md @@ -27,4 +26,4 @@ nav: extra: - version: 0.2.0 + version: 0.2.1 diff --git a/rojo.json b/rojo.json deleted file mode 100644 index dd71fc3..0000000 --- a/rojo.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "name": "roblox-requests", - "servePort": 8000, - "partitions": { - "http": { - "path": "http", - "target": "ReplicatedStorage.http" - } - } -}