Open Question: How to Generalize

[whoabuddy]

This may not be something specifically in scope for the CityCoins API, but thinking about the amount of routing we do to satisfy all the contract paths and parameters, there is a common pattern that could be generalized.

The original thought behind the CityCoins API was to make an endpoint for every contract function, and I still think specific APIs that follow this pattern could be very useful to both user interfaces and external integrations.

However, this may be useful for other projects that want to the use an API structure like this one, and I felt like the idea was worth documenting as "something to think about" when the V2 upgrades come downstream.

---

What if there were a simple route that accepted the following path and query parameters?

https://api.citycoins.co/query/deployer/contract_name/function_name?param1=value1&param2=value2

Which breaks down as:

• prefix: https://api.citycoins.co/query/
• path: deployer - deployer address of contract
• path: contract_name - contract name
• path: function_name - function name in contract
• query: param1 - function parameters, if any
• query: param2 - function parameters, if any

An example using is-block-winner:

https://api.citycoins.co/v2/SP466FNC0P7JWTNM2R9T199QRZN1MYEDTAR0KP27/miamicoin-core-v1/?blockheight=25000&address=SP466FNC0P7JWTNM2R9T199QRZN1MYEDTAR0KP27

This would essentially be a "query builder" in which you could put any contract, function, and related parameters then receive a result.

Pros:

• this would open up a way to query any contract without dependencies
• there is no additional code to add if contract functions change
• there is no effort required to query new contracts on chain
• could serve as a fallback method for getting data
  • e.g. using this method until something more official like an endpoint is implemented
  • e.g. using this method to query data only needed for some time (like the vote info)

Cons:

• knowing the correct type for the query parameters and converting them may be a challenge
• knowing how to process the types of returned data may be a challenge
• could both of those be worked around using the contract ABI?

---

Curious what others think!

Spit-balling a few more reasons I think this could be useful:

• this can be achieved with Cloudflare Workers free tier, and their pricing is very fair when scaling
• this separates the data layer from the application layer, which allows for others to build UIs, tools, and implement integrations in a consistent fashion
• this allows for caching, where a strategy could be set based on the type of data and stored in Cloudflare Workers KV
  • if data never changes, can return results directly from KV first then store if not found
  • custom TTL values can be set depending on how often data should be refreshed
  • patterns like checking if the block height changed can be applied to limit queries
• this allows low-level access to HTTP headers and responses, which can:
  • help increase security
  • solve cross-origin request problems
  • and much much more
• this allows for cron-type scripts to run using the same defined functions, which can:
  • update a user's info on a regular basis (or a list of users)
  • monitor chain state and key metrics
  • collect contract data for processing / re-use

[diopitis]

Love this idea and think worker kv's would be perfect for this! Separating the data layer would give birth to a lot more tools and use cases if cc data felt quicker to retrieve and more accessible.

[HiGregory]

Apart of what DataGovs and the Govs API is doing is building this data layer for City of Miami is this.

The layer would tie to multiple sources like CC that support city infrastructure.

[whoabuddy]

@diopitis thanks for the support, I also wonder if there's an overlap between this idea and clarigen, since the contract ABIs are exposed there's technically a way to generate the code needed. Turning this into a 1-click package sounds like a great wishlist grant actually.

The powerful part of it is how others can then integrate with your app using the same data, whether that be another user interface, a dashboard, a reporting service, a companion service, custom scripts, etc.

Plus, with a generated openapi spec the docs setup is basically pointing a script at the openapi file. Can be hosted through workers with a little HTML and route magic but KV works for static sites too.

The API only covers read-only functions though. Another missing piece would be a library for public functions that someone could install, and making that into a maintained NPM package for the project would also elevate DX.

Imagine this: you want to integrate a project and you can

• hit their API to return read-only contract data for any data in the contract
  • computed values can also be returned like /tools endpoints in CityCoins API
• install the NPM package and be able to access public contract functions

@will-at-stacks flagging you in case this sounds interesting ^

[whoabuddy]

@HiGregory The idea presented here is more of an abstract design philosophy on how to create a Stacks app where you provide a simple API that exposes contract values to allow for easier integrations, in a consistent and possibly generative matter, without the need for external dependencies like stacks.js or micro-stacks by the API users.

That said, I'm definitely interested in learning more about how we can integrate - I left comments in #48 on how we can get to next steps!