From b68aecacb9622804d449d922197d63c0ef4710cd Mon Sep 17 00:00:00 2001 From: laststylebender Date: Mon, 25 Nov 2024 18:34:47 +0530 Subject: [PATCH 1/6] - update the docs with Post request batching --- docs/directives/http.md | 61 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/directives/http.md b/docs/directives/http.md index 1780674fa..103924720 100644 --- a/docs/directives/http.md +++ b/docs/directives/http.md @@ -167,6 +167,7 @@ When `batchKey` is present, Tailcall considers the first `query` parameter to be type Post { id: Int! name: String! + userId: Int! user: User @http( url: "https://jsonplaceholder.typicode.com/users" @@ -178,6 +179,66 @@ type Post { - `query: {key: "user_id", value: "{{.value.userId}}"}]`: Instructs Tailcall CLI to generate a URL aligning the user id with `userId` from the parent `Post`, compiling a single URL for a batch of posts, such as `/users?user_id=1&user_id=2&user_id=3...user_id=10`, consolidating requests into one. +### Batching with POST Requests + +Tailcall allows you to batch multiple `POST` requests into a single upstream `POST` request, improving efficiency. + +Consider the following example where `https://jsonplaceholder.typicode.com/posts` returns the following data: + +```json title="Posts" +[ + { + "id": 1, + "name": "post-1", + "userId": 1 + }, + { + "id": 2, + "name": "post-2", + "userId": 2 + } +] +``` + +With the configuration below, a single batched `POST` request will be made to the upstream service: + +```showLineNumbers +Request: https://jsonplaceholder.typicode.com/users +Method: POST +Body: [ + { + "userId": 1, + "staticValue": "static" + }, + { + "userId": 2, + "staticValue": "static" + } + ] +``` + +Currently, only one dynamic parameter is supported in a batched `POST` request, as shown with `{{.value.userId}}` in the example. + +```graphql showLineNumbers +type Query { + posts: [Post] + @http(url: "https://jsonplaceholder.typicode.com/posts") +} + +type Post { + id: Int! + name: String! + userId: Int! + user: User + @http( + url: "https://jsonplaceholder.typicode.com/users" + method: POST + body: "{\"userId\": \"{{.value.userId}}\", \"staticValue\": \"static\"}" + batchKey: ["users", "id"] + ) +} +``` + ## onRequest The `onRequest` property accepts a string value representing the remote function to be called every time an HTTP request is initiated. Typically the remote function is defined in a linked JavaScript worker file. From 1c735067f68a35ef087bf1deacc4addc21b78767 Mon Sep 17 00:00:00 2001 From: laststylebender Date: Mon, 25 Nov 2024 18:36:54 +0530 Subject: [PATCH 2/6] - improve docs --- docs/directives/http.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/directives/http.md b/docs/directives/http.md index 103924720..24aa0a423 100644 --- a/docs/directives/http.md +++ b/docs/directives/http.md @@ -181,11 +181,13 @@ type Post { ### Batching with POST Requests -Tailcall allows you to batch multiple `POST` requests into a single upstream `POST` request, improving efficiency. +Tailcall supports batching multiple `POST` requests into a single upstream `POST` request, enhancing efficiency and reducing network overhead. -Consider the following example where `https://jsonplaceholder.typicode.com/posts` returns the following data: +#### Example Scenario -```json title="Posts" +Suppose the endpoint `https://jsonplaceholder.typicode.com/posts` returns the following data: + +```json [ { "id": 1, @@ -200,9 +202,9 @@ Consider the following example where `https://jsonplaceholder.typicode.com/posts ] ``` -With the configuration below, a single batched `POST` request will be made to the upstream service: +With the configuration below, Tailcall will consolidate these into a single batched `POST` request to the upstream service: -```showLineNumbers +```bash Request: https://jsonplaceholder.typicode.com/users Method: POST Body: [ @@ -217,12 +219,13 @@ Body: [ ] ``` -Currently, only one dynamic parameter is supported in a batched `POST` request, as shown with `{{.value.userId}}` in the example. +**Note**: Currently, only one dynamic parameter is supported in a batched `POST` request, as demonstrated with `{{.value.userId}}` in the example. + +#### GraphQL Configuration ```graphql showLineNumbers type Query { - posts: [Post] - @http(url: "https://jsonplaceholder.typicode.com/posts") + posts: [Post] @http(url: "https://jsonplaceholder.typicode.com/posts") } type Post { From 72d9179e0ae90a23201eb668ceba7b0980692ed9 Mon Sep 17 00:00:00 2001 From: laststylebender Date: Mon, 25 Nov 2024 18:46:05 +0530 Subject: [PATCH 3/6] - format fix --- docs/directives/http.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/directives/http.md b/docs/directives/http.md index 24aa0a423..795e643a6 100644 --- a/docs/directives/http.md +++ b/docs/directives/http.md @@ -225,7 +225,8 @@ Body: [ ```graphql showLineNumbers type Query { - posts: [Post] @http(url: "https://jsonplaceholder.typicode.com/posts") + posts: [Post] + @http(url: "https://jsonplaceholder.typicode.com/posts") } type Post { From d443798654ae314e13d5d419b39ada2963bfd7d2 Mon Sep 17 00:00:00 2001 From: laststylebender Date: Tue, 3 Dec 2024 18:34:28 +0530 Subject: [PATCH 4/6] - update docs --- docs/directives/http.md | 93 ++++++++++++++++++++++++++++++----------- 1 file changed, 69 insertions(+), 24 deletions(-) diff --git a/docs/directives/http.md b/docs/directives/http.md index 795e643a6..dfc0377cc 100644 --- a/docs/directives/http.md +++ b/docs/directives/http.md @@ -181,11 +181,35 @@ type Post { ### Batching with POST Requests -Tailcall supports batching multiple `POST` requests into a single upstream `POST` request, enhancing efficiency and reducing network overhead. +Tailcall can optimize multiple individual POST requests by batching them into a single upstream POST request. This feature significantly reduces network overhead and improves overall performance. -#### Example Scenario +#### How Batching Works -Suppose the endpoint `https://jsonplaceholder.typicode.com/posts` returns the following data: +When Tailcall receives multiple POST requests that share the same endpoint but have different parameters, it: + +1. Collects these requests into a batch +2. Transforms them into a single POST request with an array of bodies +3. Sends this consolidated request to the upstream service +4. Maps the responses back to individual results + +#### Example + +Let's say your GraphQL query needs to fetch user details for multiple posts: + +```graphql +query { + posts { + id + name + user { + id + name + } + } +} +``` + +The posts endpoint returns: ```json [ @@ -202,47 +226,68 @@ Suppose the endpoint `https://jsonplaceholder.typicode.com/posts` returns the fo ] ``` -With the configuration below, Tailcall will consolidate these into a single batched `POST` request to the upstream service: +Instead of making separate POST requests for each user, Tailcall will batch them into a single request: ```bash -Request: https://jsonplaceholder.typicode.com/users -Method: POST -Body: [ - { - "userId": 1, - "staticValue": "static" - }, - { - "userId": 2, - "staticValue": "static" - } - ] +POST https://jsonplaceholder.typicode.com/users +Content-Type: application/json +Body: +[ + { + "userId": 1, + "staticValue": "static" + }, + { + "userId": 2, + "staticValue": "static" + } +] ``` -**Note**: Currently, only one dynamic parameter is supported in a batched `POST` request, as demonstrated with `{{.value.userId}}` in the example. +#### Configuration -#### GraphQL Configuration +To enable batching, configure your schema with the appropriate directives: -```graphql showLineNumbers +```graphql type Query { posts: [Post] @http(url: "https://jsonplaceholder.typicode.com/posts") } type Post { - id: Int! + id: ID! name: String! - userId: Int! - user: User + user: User! @http( url: "https://jsonplaceholder.typicode.com/users" method: POST - body: "{\"userId\": \"{{.value.userId}}\", \"staticValue\": \"static\"}" - batchKey: ["users", "id"] + body: { + userId: "{{.value.userId}}" + staticValue: "static" + } + batchKey: ["userId"] ) } + +type User { + id: ID! + name: String! +} ``` +#### Limitations + +- Currently supports only one dynamic parameter per batched request +- All requests in a batch must share the same endpoint and method +- The dynamic parameter must be referenced using the `{{.value.fieldName}}` syntax + +#### Benefits + +- Reduced network overhead +- Improved response times +- Better resource utilization +- Lower upstream server load + ## onRequest The `onRequest` property accepts a string value representing the remote function to be called every time an HTTP request is initiated. Typically the remote function is defined in a linked JavaScript worker file. From 831923445ef1c56a9f8dea0b4f09017a02681f7d Mon Sep 17 00:00:00 2001 From: amit Date: Tue, 10 Dec 2024 13:25:26 -0800 Subject: [PATCH 5/6] update flow and text --- docs/directives/http.md | 211 +++++++++++++++++++--------------------- 1 file changed, 102 insertions(+), 109 deletions(-) diff --git a/docs/directives/http.md b/docs/directives/http.md index 00053b788..c91de4194 100644 --- a/docs/directives/http.md +++ b/docs/directives/http.md @@ -171,115 +171,6 @@ type Post { - `query: {key: "user_id", value: "{{.value.userId}}"}]`: Instructs Tailcall CLI to generate a URL aligning the user id with `userId` from the parent `Post`, compiling a single URL for a batch of posts, such as `/users?user_id=1&user_id=2&user_id=3...user_id=10`, consolidating requests into one. -### Batching with POST Requests - -Tailcall can optimize multiple individual POST requests by batching them into a single upstream POST request. This feature significantly reduces network overhead and improves overall performance. - -#### How Batching Works - -When Tailcall receives multiple POST requests that share the same endpoint but have different parameters, it: - -1. Collects these requests into a batch -2. Transforms them into a single POST request with an array of bodies -3. Sends this consolidated request to the upstream service -4. Maps the responses back to individual results - -#### Example - -Let's say your GraphQL query needs to fetch user details for multiple posts: - -```graphql -query { - posts { - id - name - user { - id - name - } - } -} -``` - -The posts endpoint returns: - -```json -[ - { - "id": 1, - "name": "post-1", - "userId": 1 - }, - { - "id": 2, - "name": "post-2", - "userId": 2 - } -] -``` - -Instead of making separate POST requests for each user, Tailcall will batch them into a single request: - -```bash -POST https://jsonplaceholder.typicode.com/users -Content-Type: application/json -Body: -[ - { - "userId": 1, - "staticValue": "static" - }, - { - "userId": 2, - "staticValue": "static" - } -] -``` - -#### Configuration - -To enable batching, configure your schema with the appropriate directives: - -```graphql -type Query { - posts: [Post] - @http(url: "https://jsonplaceholder.typicode.com/posts") -} - -type Post { - id: ID! - name: String! - user: User! - @http( - url: "https://jsonplaceholder.typicode.com/users" - method: POST - body: { - userId: "{{.value.userId}}" - staticValue: "static" - } - batchKey: ["userId"] - ) -} - -type User { - id: ID! - name: String! -} -``` - -#### Limitations - -- Currently supports only one dynamic parameter per batched request -- All requests in a batch must share the same endpoint and method -- The dynamic parameter must be referenced using the `{{.value.fieldName}}` syntax - -#### Benefits - -- Reduced network overhead -- Improved response times -- Better resource utilization -- Lower upstream server load - ### onRequest The `onRequest` property accepts a string value representing the remote function to be called every time an HTTP request is initiated. Typically the remote function is defined in a linked JavaScript worker file. @@ -355,6 +246,108 @@ A boolean flag, if set to `true`, will enable deduplication of IO operations to ) ``` +## Batching with POST Requests + +In some cases, your batch API might use a POST request that accepts a list of items for processing. Tailcall can batch these requests similarly to how it handles GET requests, but instead of sending the input in query parameters, it sends them in the request body. + +### How Batching Works + +When Tailcall receives multiple POST requests that share the same endpoint but have different parameters, it: + +1. Collects these requests +2. Transforms them into a single POST request with an array of objects in the body +3. Sends this consolidated request to the upstream service +4. Maps the responses back to individual results + +### Configuration + +To enable batching, configure your schema as follows: + +```graphql +type Query { + posts: [Post] + @http(url: "https://jsonplaceholder.typicode.com/posts") +} + +type Post { + id: ID! + name: String! + user: User! + @http( + url: "https://jsonplaceholder.typicode.com/users" + method: POST + body: { + userId: "{{.value.userId}}" + staticValue: "static" + } + batchKey: ["userId"] + ) +} + +type User { + id: ID! + name: String! +} +``` + +In this example, the `posts` query fetches a list of posts, and the `user` field fetches user details for each post. The `batchKey` parameter groups the user requests into a single POST request, enhancing efficiency. + +Let's say your GraphQL query needs to fetch user details for multiple posts: + +```graphql +query { + posts { + id + name + user { + id + name + } + } +} +``` + +The posts endpoint returns: + +```json +[ + { + "id": 1, + "name": "post-1", + "userId": 1 + }, + { + "id": 2, + "name": "post-2", + "userId": 2 + } +] +``` + +Instead of making separate POST requests for each user, Tailcall will batch them into a single request: + +```bash +POST https://jsonplaceholder.typicode.com/users +Content-Type: application/json +Body: +[ + { + "userId": 1, + "staticValue": "static" + }, + { + "userId": 2, + "staticValue": "static" + } +] +``` + +### Limitations + +- Currently, supports only one dynamic parameter per batched request +- All requests in a batch must share the same endpoint and method +- The dynamic parameter must be referenced using the `{{.value.fieldName}}` syntax + ## Combining Multiple Directives The `@http` directive can be used in combination with other [resolvable directives](../directives.md#resolvable-directives), with results merged deeply. This allows for powerful and flexible resolver configurations. From d72cf40ee950b812aa285a01d9d5b3339db9d20e Mon Sep 17 00:00:00 2001 From: amit Date: Tue, 10 Dec 2024 13:27:27 -0800 Subject: [PATCH 6/6] update flow and text --- docs/directives/http.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/directives/http.md b/docs/directives/http.md index c91de4194..eb09a137f 100644 --- a/docs/directives/http.md +++ b/docs/directives/http.md @@ -250,7 +250,7 @@ A boolean flag, if set to `true`, will enable deduplication of IO operations to In some cases, your batch API might use a POST request that accepts a list of items for processing. Tailcall can batch these requests similarly to how it handles GET requests, but instead of sending the input in query parameters, it sends them in the request body. -### How Batching Works +### Mechanism When Tailcall receives multiple POST requests that share the same endpoint but have different parameters, it: @@ -342,7 +342,7 @@ Body: ] ``` -### Limitations +### Current Limitations - Currently, supports only one dynamic parameter per batched request - All requests in a batch must share the same endpoint and method