api client types and documentation

[aulneau]

Hey all :)

The new openapi-fetch based client is pretty hard and confusing to use, could you add some basic documentation? 🙏

Additionally, I'm having a really hard time getting types to work correctly, I have to wrangle them pretty explicitly:

Let me know if I'm missing anything or doing this incorrectly btw!

Thanks!!

[aryzing]

I'm with you @aulneau. I even created another API client just to provide myself with a friendlier API.

Perhaps it would be worthwhile to look into trpc or Elysia for the Stacks API. Elysia can also use TypeBox, supports typing of both params and body, and has OpenAPI plugins.

By inferring client types directly from the API definition, these tools are able to provide great DX. No need to wrangle a typed client together from the OpenAPI spec of the original typed API definition.

[zone117x]

Hi @aulneau, the error schema isn't defined for many of the routes which is why you're seeing the error: never type issue. The route definition here needs a status 4xx response schema defined:

stacks-blockchain-api/src/api/routes/bns/addresses.ts

Lines 37 to 51 in f0176a0

	response: {
	200: Type.Object(
	{
	names: Type.Array(
	Type.String({
	examples: ['muneeb.id'],
	})
	),
	},
	{
	title: 'BnsNamesOwnByAddressResponse',
	description: 'Retrieves a list of names owned by the address provided.',
	}
	),
	},

For now you can check the request status like:

Here's an example of a route with correct error status schemas defined:

stacks-blockchain-api/src/api/routes/search.ts

Lines 277 to 289 in f0176a0

	response: {
	200: Type.Object({
	found: Type.Literal(true),
	result: SearchResultSchema,
	}),
	404: Type.Object({
	found: Type.Literal(false),
	result: Type.Object({
	entity_type: Type.Enum(SearchResultType),
	}),
	error: Type.String(),
	}),
	},