From 8ec1d2f5137d4372b493cf6c64707ae21b5ba19b Mon Sep 17 00:00:00 2001 From: Bruno Calza Date: Wed, 22 May 2024 16:15:25 -0300 Subject: [PATCH 1/2] add support for params in POST /query Signed-off-by: Bruno Calza --- specs/validator/tableland-openapi-spec.yaml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/specs/validator/tableland-openapi-spec.yaml b/specs/validator/tableland-openapi-spec.yaml index 05a3eea..6813e68 100644 --- a/specs/validator/tableland-openapi-spec.yaml +++ b/specs/validator/tableland-openapi-spec.yaml @@ -363,6 +363,17 @@ components: description: The SQL read query statement type: string example: select * from healthbot_80002_1 + params: + description: The values of query parameters + type: array + items: + type: object + oneOf: + - type: string + - type: number + - type: integer + - type: boolean + example: [1, "hello", null, true] format: description: > The requested response format: From 014dec92631e41717dd56d7f24fd8019e0d3a36f Mon Sep 17 00:00:00 2001 From: Bruno Calza Date: Fri, 24 May 2024 11:39:49 -0300 Subject: [PATCH 2/2] changes README and Specification based on new spec Signed-off-by: Bruno Calza --- specs/validator/README.md | 305 ++++++++++++++++----------- specs/validator/Specification.md | 340 +++++++++++++++++++------------ 2 files changed, 390 insertions(+), 255 deletions(-) diff --git a/specs/validator/README.md b/specs/validator/README.md index c812dd6..650a78c 100644 --- a/specs/validator/README.md +++ b/specs/validator/README.md @@ -10,22 +10,13 @@ This general API specification is used to automatically generate clients and bac ### Table of Contents -- [Synopsis](#synopsis) - - [Table of Contents](#table-of-contents) - [Query the network](#query-the-network) - - [Detailed descriptions](#detailed-descriptions) - - [Enumerated Values](#enumerated-values) - [Query the network (POST)](#query-the-network-post) - [Get transaction status](#get-transaction-status) - [Get table information](#get-table-information) - [Get health status](#get-health-status) - [Get version information](#get-version-information) - - [Properties](#properties) - - [Properties](#properties-1) - - [Properties](#properties-2) - - [Properties](#properties-3) - - [Properties](#properties-4) - - [Properties](#properties-5) +- [Schemas](#schemas)

@@ -81,7 +72,7 @@ Query the Tableland network > Code samples -```shell +``` shell # You can also use wget curl -X GET https://testnets.tableland.network/api/v1/query?statement=select%20%2A%20from%20healthbot_80002_1 \ -H 'Accept: application/json' @@ -95,12 +86,12 @@ Returns the results of a SQL read query against the Tableland network Parameters

-| Name | In | Type | Required | Description | -| --------- | ----- | ------- | -------- | ------------------------------------------------------------------------------------------- | -| statement | query | string | true | The SQL read query statement | -| format | query | string | false | The requested response format: | -| extract | query | boolean | false | Whether to extract the JSON object from the single property of the surrounding JSON object. | -| unwrap | query | boolean | false | Whether to unwrap the returned JSON objects from their surrounding array. | +| Name | In | Type | Required | Description | +|----|----|----|----|----| +| statement | query | string | true | The SQL read query statement | +| format | query | string | false | The requested response format: | +| extract | query | boolean | false | Whether to extract the JSON object from the single property of the surrounding JSON object. | +| unwrap | query | boolean | false | Whether to unwrap the returned JSON objects from their surrounding array. | #### Detailed descriptions @@ -111,7 +102,7 @@ query results as a JSON object with columns and rows properties. #### Enumerated Values | Parameter | Value | -| --------- | ------- | +|-----------|---------| | format | objects | | format | table | @@ -119,7 +110,7 @@ query results as a JSON object with columns and rows properties. > 200 Response -```json +``` json {} ``` @@ -127,12 +118,12 @@ query results as a JSON object with columns and rows properties. Responses -| Status | Meaning | Description | Schema | -| ------ | ------------------------------------------------------------------ | ----------------------------- | ------ | -| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | Inline | -| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid query/statement value | None | -| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Row Not Found | None | -| 429 | [Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) | Too Many Requests | None | +| Status | Meaning | Description | Schema | +|----|----|----|----| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | Inline | +| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid query/statement value | None | +| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Row Not Found | None | +| 429 | [Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) | Too Many Requests | None |

Response Schema @@ -147,7 +138,7 @@ This operation does not require authentication > Code samples -```shell +``` shell # You can also use wget curl -X POST https://testnets.tableland.network/api/v1/query \ -H 'Content-Type: application/json' \ @@ -160,9 +151,15 @@ Returns the results of a SQL read query against the Tableland network > Body parameter -```json +``` json { "statement": "select * from healthbot_80002_1", + "params": [ + 1, + "hello", + null, + true + ], "format": "objects", "extract": false, "unwrap": false @@ -173,15 +170,15 @@ Returns the results of a SQL read query against the Tableland network Parameters

-| Name | In | Type | Required | Description | -| ---- | ---- | --------------------- | -------- | ------------------------------------------------------ | -| body | body | [Query](#schemaquery) | true | A JSON containing the statement and additional options | +| Name | In | Type | Required | Description | +|----|----|----|----|----| +| body | body | [Query](#schemaquery) | true | A JSON containing the statement and additional options | > Example responses > 200 Response -```json +``` json {} ``` @@ -189,12 +186,12 @@ Parameters Responses -| Status | Meaning | Description | Schema | -| ------ | ------------------------------------------------------------------ | ----------------------------- | ------ | -| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | Inline | -| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid query/statement value | None | -| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Row Not Found | None | -| 429 | [Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) | Too Many Requests | None | +| Status | Meaning | Description | Schema | +|----|----|----|----| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | Successful operation | Inline | +| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid query/statement value | None | +| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Row Not Found | None | +| 429 | [Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) | Too Many Requests | None |

Response Schema @@ -216,7 +213,7 @@ Get information about transaction progress > Code samples -```shell +``` shell # You can also use wget curl -X GET https://testnets.tableland.network/api/v1/receipt/{chainId}/{transactionHash} \ -H 'Accept: application/json' @@ -231,7 +228,7 @@ Parameters

| Name | In | Type | Required | Description | -| --------------- | ---- | -------------- | -------- | ------------------------------- | +|-----------------|------|----------------|----------|---------------------------------| | chainId | path | integer(int32) | true | The parent chain to target | | transactionHash | path | string | true | The transaction hash to request | @@ -239,10 +236,13 @@ Parameters > 200 Response -```json +``` json { "table_id": "1", - "table_ids": ["1", "2"], + "table_ids": [ + "1", + "2" + ], "transaction_hash": "0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b", "block_number": 27055540, "chain_id": 80002, @@ -255,12 +255,12 @@ Parameters Responses -| Status | Meaning | Description | Schema | -| ------ | ------------------------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------- | -| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | successful operation | [TransactionReceipt](#schematransactionreceipt) | -| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid chain identifier or transaction hash format | None | -| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | No transaction receipt found with the provided hash | None | -| 429 | [Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) | Too Many Requests | None | +| Status | Meaning | Description | Schema | +|----|----|----|----| +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | successful operation | [TransactionReceipt](#schematransactionreceipt) | +| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid chain identifier or transaction hash format | None | +| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | No transaction receipt found with the provided hash | None | +| 429 | [Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) | Too Many Requests | None |