update openapi3

pinax-network · Sep 27, 2024 · 7d28769 · 7d28769
1 parent f8ddeb0
commit 7d28769
Show file tree

Hide file tree

Showing 9 changed files with 97 additions and 152 deletions.
diff --git a/README.md b/README.md
@@ -38,13 +38,10 @@
 | GET <br>`text/plain` | `/health` | Checks database connection |
 | GET <br>`text/plain` | `/metrics` | [Prometheus](https://prometheus.io/) metrics |
 
-## GraphQL
-
-Go to `/graphql` for a GraphIQL interface.
-
 ### `X-Api-Key`
 
 Use the `Variables` tab at the bottom to add your API key:
+
 ```json
 {
   "X-Api-Key": "changeme"
@@ -60,7 +57,7 @@ Use the `Variables` tab at the bottom to add your API key:
 ## Requirements
 
 - [ClickHouse](clickhouse.com/), databases should follow a `{chain}_tokens_{version}` naming scheme. Database tables can be setup using the [`schema.sql`](./schema.sql) definitions created by the [`create_schema.sh`](./create_schema.sh) script.
-- A [Substream sink](https://substreams.streamingfast.io/reference-and-specs/glossary#sink) for loading data into ClickHouse. We recommend [Substreams Sink ClickHouse](https://github.com/pinax-network/substreams-sink-clickhouse/) or [Substreams Sink SQL](https://github.com/pinax-network/substreams-sink-sql). You should use the generated [`protobuf` files](static/@typespec/protobuf) to build your substream. This Token API makes use of the [`substreams-antelope-tokens`](https://github.com/pinax-network/substreams-antelope-tokens/) substream.
+- A [Substream sink](https://substreams.streamingfast.io/reference-and-specs/glossary#sink) for loading data into ClickHouse. We recommend [Substreams Sink ClickHouse](https://github.com/pinax-network/substreams-sink-clickhouse/) or [Substreams Sink SQL](https://github.com/pinax-network/substreams-sink-sql). This Token API makes use of the [`substreams-antelope-tokens`](https://github.com/pinax-network/substreams-antelope-tokens/) substream.
 
 ### API stack architecture
 
@@ -129,7 +126,6 @@ echo "CREATE DATABASE eos_tokens_v1 ON CLUSTER <cluster>" | clickhouse client -h
 ./create_schema.sh -o /tmp/schema.sql -c <cluster>
 ```
 
-
 ## [`Bun` Binary Releases](https://github.com/pinax-network/antelope-token-api/releases)
 
 > [!WARNING]
@@ -179,21 +175,25 @@ VERBOSE=true
 - Pull from GitHub Container registry
 
 **For latest tagged release**
+
 ```bash
 docker pull ghcr.io/pinax-network/antelope-token-api:latest
 ```
 
 **For head of `main` branch**
+
 ```bash
 docker pull ghcr.io/pinax-network/antelope-token-api:develop
 ```
 
 - Build from source
+
 ```bash
 docker build -t antelope-token-api .
 ```
 
 - Run with `.env` file
+
 ```bash
 docker run -it --rm --env-file .env ghcr.io/pinax-network/antelope-token-api
 ```
@@ -207,12 +207,13 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 Install [Bun](https://bun.sh/)
 
 ```console
-$ bun install
-$ bun dev
+bun install
+bun dev
 ```
 
 **Tests**
+
 ```console
-$ bun lint
-$ bun test
+bun lint
+bun test
 ```
diff --git a/package.json b/package.json
@@ -48,7 +48,6 @@
     "@typespec/compiler": "latest",
     "@typespec/openapi": "latest",
     "@typespec/openapi3": "latest",
-    "@typespec/protobuf": "latest",
     "bun-types": "latest",
     "openapi-to-graphql-cli": "^3.0.7",
     "typescript": "latest"

diff --git a/src/types/zod.gen.ts b/src/types/zod.gen.ts
@@ -106,23 +106,23 @@ export const usageTransfersAccountQueryResponseSchema = z.object({ "data": z.arr
 export type UsageTransfersAccountQueryResponseSchema = z.infer<typeof usageTransfersAccountQueryResponseSchema>;
 
 
-export const usageHeadQueryParamsSchema = z.object({ "limit": z.coerce.number().int().default(10).optional(), "page": z.coerce.number().int().default(1).optional() }).optional();
-export type UsageHeadQueryParamsSchema = z.infer<typeof usageHeadQueryParamsSchema>;
+export const monitoringHeadQueryParamsSchema = z.object({ "limit": z.coerce.number().int().default(10).optional(), "page": z.coerce.number().int().default(1).optional() }).optional();
+export type MonitoringHeadQueryParamsSchema = z.infer<typeof monitoringHeadQueryParamsSchema>;
 /**
  * @description Head block information.
  */
-export const usageHead200Schema = z.object({ "data": z.array(z.object({ "block_num": z.coerce.number().int(), "block_id": z.coerce.string() })), "meta": z.lazy(() => responseMetadataSchema) });
-export type UsageHead200Schema = z.infer<typeof usageHead200Schema>;
+export const monitoringHead200Schema = z.object({ "data": z.array(z.object({ "block_num": z.coerce.number().int(), "block_id": z.coerce.string() })), "meta": z.lazy(() => responseMetadataSchema) });
+export type MonitoringHead200Schema = z.infer<typeof monitoringHead200Schema>;
 /**
  * @description An unexpected error response.
  */
-export const usageHeadErrorSchema = z.lazy(() => apiErrorSchema);
-export type UsageHeadErrorSchema = z.infer<typeof usageHeadErrorSchema>;
+export const monitoringHeadErrorSchema = z.lazy(() => apiErrorSchema);
+export type MonitoringHeadErrorSchema = z.infer<typeof monitoringHeadErrorSchema>;
 /**
  * @description Head block information.
  */
-export const usageHeadQueryResponseSchema = z.object({ "data": z.array(z.object({ "block_num": z.coerce.number().int(), "block_id": z.coerce.string() })), "meta": z.lazy(() => responseMetadataSchema) });
-export type UsageHeadQueryResponseSchema = z.infer<typeof usageHeadQueryResponseSchema>;
+export const monitoringHeadQueryResponseSchema = z.object({ "data": z.array(z.object({ "block_num": z.coerce.number().int(), "block_id": z.coerce.string() })), "meta": z.lazy(() => responseMetadataSchema) });
+export type MonitoringHeadQueryResponseSchema = z.infer<typeof monitoringHeadQueryResponseSchema>;
 
  /**
  * @description OK or ApiError.
@@ -317,16 +317,16 @@ export type DocsVersionQueryResponseSchema = z.infer<typeof docsVersionQueryResp
             default: usageTransfersAccountQueryResponseSchema
         },
         errors: {}
-    }, "Usage_head": {
+    }, "Monitoring_head": {
         request: undefined,
         parameters: {
             path: undefined,
-            query: usageHeadQueryParamsSchema,
+            query: monitoringHeadQueryParamsSchema,
             header: undefined
         },
         responses: {
-            200: usageHeadQueryResponseSchema,
-            default: usageHeadQueryResponseSchema
+            200: monitoringHeadQueryResponseSchema,
+            default: monitoringHeadQueryResponseSchema
         },
         errors: {}
     }, "Monitoring_health": {
@@ -445,7 +445,7 @@ export const paths = { "/account/balances": {
     }, "/account/transfers": {
         get: operations["Usage_transfersAccount"]
     }, "/head": {
-        get: operations["Usage_head"]
+        get: operations["Monitoring_head"]
     }, "/health": {
         get: operations["Monitoring_health"]
     }, "/metrics": {

diff --git a/src/typespec/main.tsp b/src/typespec/main.tsp
@@ -1,5 +1,4 @@
 /**
  * Main file to allow compiling for both protobuf and openapi3 specs with single command `tsp compile .`
  */
-import "./protobuf.tsp";
 import "./openapi3.tsp";
diff --git a/src/typespec/openapi3.tsp b/src/typespec/openapi3.tsp
@@ -9,11 +9,7 @@ using TypeSpec.OpenAPI;
     title: "Antelope Token Api",
 })
 @info({
-    summary: "Tokens information from the Antelope blockchains, powered by Substreams",
-    license: {
-        name: "MIT",
-        url: "https://github.com/pinax-network/antelope-token-api/blob/4f4bf36341b794c0ccf5b7a14fdf810be06462d2/LICENSE",
-    },
+    description: "Tokens information from the Antelope blockchains, powered by Substreams",
     version: "6.1.0",
 }) // From @typespec/openapi
 //@server("https://eos.api.pinax.network/v1", "EOS V1 Api Endpoint")
@@ -96,13 +92,13 @@ alias PaginationQueryParams = {
     @query page?: uint64 = 1;
 };
 
-@tag("Usage")
 interface Usage {
     /**
         Token balances of an account.
         @returns Array of balances.
     */
-    @summary("Token balances")
+    @tag("Account")
+    @summary("Account token balances")
     @route("/account/balances")
     @get
     @useAuth(ApiKeyAuth<ApiKeyLocation.header, ApiKeyHeader>)
@@ -117,7 +113,8 @@ interface Usage {
         Historical token balances of an account.
         @returns Array of balances.
     */
-    @summary("Historical token balances")
+    @tag("Account")
+    @summary("Account historical token balances")
     @route("/account/balances/historical")
     @get
     @useAuth(ApiKeyAuth<ApiKeyLocation.header, ApiKeyHeader>)
@@ -130,21 +127,29 @@ interface Usage {
     ): ApiResponse<UsageResponse<BalanceChange[]>>;
 
     /**
-        Current head block for which data is available (can be lower than head block of the chain).
-        @returns Head block information.
+        All transfers related to an account.
+        @returns Array of transfers.
     */
-    @summary("Head block information")
-    @route("/head")
+    @tag("Account")
+    @summary("Account token transfers")
+    @route("/account/transfers")
     @get
-    head(...PaginationQueryParams): ApiResponse<UsageResponse<{
-        block_num: BlockInfo.block_num;
-        block_id: string;
-    }[]>>;
+    @useAuth(ApiKeyAuth<ApiKeyLocation.header, ApiKeyHeader>)
+    transfersAccount(
+        @query account: BalanceChange.account,
+        @query(#{ explode: false }) block_range?: BlockRange,
+        @query from?: Transfer.from,
+        @query to?: Transfer.to,
+        @query contract?: TokenIdentifier.contract,
+        @query symcode?: TokenIdentifier.symcode,
+        ...PaginationQueryParams,
+    ): ApiResponse<UsageResponse<Transfer[]>>;
 
     /**
         List of holders of a token.
         @returns Array of accounts.
     */
+    @tag("Tokens")
     @summary("Token holders")
     @route("/tokens/holders")
     @get
@@ -159,6 +164,7 @@ interface Usage {
         Total supply for a token.
         @returns Array of supplies.
     */
+    @tag("Tokens")
     @summary("Token supply")
     @route("/tokens/supplies")
     @get
@@ -175,6 +181,7 @@ interface Usage {
         List of available tokens.
         @returns Array of token identifier.
     */
+    @tag("Tokens")
     @summary("Tokens")
     @route("/tokens")
     @get
@@ -187,6 +194,7 @@ interface Usage {
         All transfers related to a token.
         @returns Array of transfers.
     */
+    @tag("Transfers")
     @summary("Token transfers")
     @route("/transfers")
     @get
@@ -198,28 +206,11 @@ interface Usage {
         ...PaginationQueryParams,
     ): ApiResponse<UsageResponse<Transfer[]>>;
 
-    /**
-        All transfers related to an account.
-        @returns Array of transfers.
-    */
-    @summary("Token transfers from and to an account")
-    @route("/account/transfers")
-    @get
-    @useAuth(ApiKeyAuth<ApiKeyLocation.header, ApiKeyHeader>)
-    transfersAccount(
-        @query account: BalanceChange.account,
-        @query(#{ explode: false }) block_range?: BlockRange,
-        @query from?: Transfer.from,
-        @query to?: Transfer.to,
-        @query contract?: TokenIdentifier.contract,
-        @query symcode?: TokenIdentifier.symcode,
-        ...PaginationQueryParams,
-    ): ApiResponse<UsageResponse<Transfer[]>>;
-
     /**
         Specific transfer related to a token.
         @returns Array of transfers.
     */
+    @tag("Transfers")
     @summary("Token transfer")
     @route("/transfers/id")
     @get
@@ -278,4 +269,16 @@ interface Monitoring {
     @route("/metrics")
     @get
     metrics(): ApiResponse<string>;
+
+    /**
+        Current head block for which data is available (can be lower than head block of the chain).
+        @returns Head block information.
+    */
+    @summary("Head block information")
+    @route("/head")
+    @get
+    head(...PaginationQueryParams): ApiResponse<UsageResponse<{
+        block_num: BlockInfo.block_num;
+        block_id: string;
+    }[]>>;
 }
diff --git a/src/typespec/protobuf.tsp b/src/typespec/protobuf.tsp