repos / starfx

commit

de53ffa

parent

83e2769

author

Eric Bower

date

2024-02-16 19:55:25 +0000 UTC

docs: endpoints

 1@@ -48,7 +48,10 @@ func main() {
 2 				pdocs.AnchorTagSitemap("Enforcing fetch response type"),
 3 				pdocs.AnchorTagSitemap("The same API endpoints but different logic"),
 4 				pdocs.AnchorTagSitemap("Using variables inside the API endpoint"),
 5+				pdocs.AnchorTagSitemap("ctx.request"),
 6 				{ Text: "Using ctx.req", Href: "using-ctxreq" },
 7+				pdocs.AnchorTagSitemap("ctx.response"),
 8+				pdocs.AnchorTagSitemap("ctx.json"),
 9 				pdocs.AnchorTagSitemap("Middleware automation"),
10 			},
11 		},

 1@@ -143,12 +143,19 @@ The first part of the array is what is used for the router, everything else is
 2 unused. This lets you create as many different variations of calling that
 3 endpoint that you need.
 4 
 5+# `ctx.request`
 6+
 7+This is a `Request` object that will feed directly into a `fetch` request.
 8+End-users are able to manipulate it however they want regardless of what was set
 9+on it previously. We have mdw that will automatically manipulate it but it all
10+lives inside the mdw stack that the end-user can control.
11+
12 # Using `ctx.req`
13 
14 `ctx.req` is a helper function to merge what currently exists inside
15 `ctx.request` with new properties. It is gaurenteed to return a valid `Request`
16-object and performs a deep merge on `ctx.request` and what the user provides to
17-it.
18+object and performs a deep merge between `ctx.request` and what the user
19+provides to it.
20 
21 ```ts
22 const fetchUsers = api.get("/users", function*(ctx, next) {
23@@ -162,6 +169,16 @@ const fetchUsers = api.get("/users", function*(ctx, next) {
24 }
25 ```
26 
27+# `ctx.response`
28+
29+This is a fetch `Response` object that our `mdw.fetch` will fill automatically.
30+
31+# `ctx.json`
32+
33+Our `mdw.fetch` will automatically fill this value as a `Result` type derived
34+from `Response.json`. Success or failure of this property is determined by
35+`Response.ok` and if we can successully call `Response.json` without errors.
36+
37 # Middleware automation
38 
39 Because endpoints use the same powerful middleware system employed by thunks, we