Back to Blog
Snag V2 Docs Journey: Building a Type-Safe, Scalable API Documentation Process
Logan Chaplin
Mar 6, 2025
·
6 min read
Introduction
In Web3 scalability and maintainability are paramount. That’s why Snag evolved its API documentation and process for version 2 (V2) of its API, tackling challenges related to type safety, scalability, and developer experience. We utilized the latest technologies and methodologies to create a robust, type-safe API and documentation system that not only meets our current needs but sets us up for future growth.
From White-Label Marketplace to Loyalty Solutions
Snag began its journey as a white-label marketplace solution, empowering hundreds of projects to improve their digital product. Today we help top projects and blockchains like Pudgy Penguins, Flow, Apechain, Yuga, Wilder World, Jarritos, Rolling Loud and dozens of other top brands who leverage blockchain onboard new users and drive engagement. As our client base grew, so did their needs, our partners sought innovative ways to engage their communities, particularly through our API-based loyalty solution which can be adapted to any front end experience.
With last month’s v2 Docs release we migrated our endpoints to ts-rest, revamped our documentation page with Mintlify, and deployed a new SDK, dramatically improving the developer experience for our partners.
Developing the Loyalty Engine
The Double Entry Ledger: Auditability and Data Consistency
To meet this demand, we developed a loyalty engine consisting of two main components: the ledger and the rule engine. At the heart of this system is our double-entry ledger, which offers significant benefits like auditability and data consistency. Every transaction is recorded in multiple places, ensuring that our partners can trust the integrity of their loyalty programs.
Loyalty Rules and Templates
We consistently release new loyalty rules—approximately one every week—and have amassed a comprehensive collection to cater to diverse partner needs. These rules are served through our loyalty template, which, much like our marketplace template, allows partners to customize almost every aspect via our admin panel while maintaining out of the box compatibility with our loyalty engine.
Scaling for High Throughput
As we expanded, ensuring that our loyalty rules function seamlessly under high throughput became mission-critical. We needed to guarantee that our system could handle the significant demands of our largest partners without compromising performance or reliability.
Exposing Endpoints for Deeper Integration
Initial API Exposure and Documentation with Swagger
Recognizing the need for deeper integration with our partners’ existing digital properties, we exposed our transaction endpoints. This move allowed developers to award points in an auditable way through our API. To document these external endpoints, we used Swagger comments—multi-line comments within the endpoint code that describe the resource. This approach enabled us to create an OpenAPI specification easily and host it through our existing application.
Expanding to Internal Endpoints
As our partners’ needs grew, requiring fully customized loyalty frontends, we started exposing our internal endpoints. We maintained the same pattern of using YAML documentation above each endpoint. This strategy initially worked well, but as the number of endpoints increased, cracks began to show.
The Documentation Challenge
Maintaining a few Swagger comments was manageable, but with over 20 endpoints, our documentation started to drift out of sync with the actual code. We needed a solution—and fast. Our requirements were clear:
Auto-documentation: Reduce manual overhead in maintaining docs.
Minimal Build Impact: Avoid significant increases in build and dev server times.
Full Type Safety: Ensure that our API contracts are type-safe.
Evaluating Solutions: TRPC vs. Ts-rest
TRPC: Strengths and Limitations
We first considered TRPC, however, TRPC would convert our RESTful endpoints into RPC endpoints, which was a dealbreaker for us. We needed to maintain REST compatibility to allow simple operations, and with our substantial number of endpoints, TRPC could impact the development experience for the team.
Ts-rest: Checking All the Boxes
Enter Ts-rest. This solution met all our criteria:
Maintains REST Endpoints: No need to shift to RPC.
Incrementally Adoptable Client: Allows for gradual integration.
No Build Step: Simplifies the build process.
Minimal Performance Penalty: Efficient and lightweight.
OpenAPI Spec Generation: Can generate specs directly from the contract.
Migrating to Ts-rest
Typing All Requests and Responses
Our endpoints had expanded organically, resulting in some lacking types on the server side. Ts-rest requires all requests and responses to be fully typed, which posed the biggest challenge in our migration. We tackled this by adding request and response types to Zod schemas and documenting them with OpenAPI.
Incremental Updates and Integration
We approached the migration methodically, updating each endpoint one by one to ensure full type safety. We pushed incremental updates, closely monitoring for any issues before proceeding to the next endpoint. This careful strategy allowed us to maintain stability throughout the transition.
Combining Legacy Docs with OpenAPI Spec
To ensure a seamless experience for our partners, we combined our legacy documentation with the new OpenAPI spec. This approach provided a continuous API docs page, bridging the gap between old and new and making the transition smoother for everyone involved.
The Power of Type Safety
Achieving type safety created complete confidence in our generated OpenAPI spec. If any changes occur downstream of the endpoints, the application won’t build, alerting us to discrepancies immediately. This self-documenting code ensures that any changes to response schemas are automatically reflected in the documentation, significantly increasing our team’s confidence and development speed.
Enhancing Documentation with Mintlify
While our self-generated Swagger docs were functional, they were still in the out of the box open source swagger ui. We wanted our documentation to look polished and professional, especially for our business development team and partners. We chose Mintlify for our documentation needs due to its zero-dependency setup, sleek design, and ease of development.
Auto-Generating SDKs with Stainless
Leveraging our OpenAPI spec, we found it straightforward to auto-generate an SDK wrapper for all our endpoints. We utilized Stainless to generate our TypeScript client, which has been working flawlessly. As we update our spec, Stainless creates a new SDK release that we can test and deploy to npm. This setup also provides the flexibility to generate clients in other languages based on our partners’ needs.
Key Learnings
Types Are Your Friend: Incorporating types pays dividends in the long run. Retrofitting types into an existing codebase is cumbersome, so we advocate for a type safety strategy early in development when building for scale.
The Value of Ts-rest: Ts-rest proved to be an invaluable tool in our transition. The active community on their Discord channel was instrumental when facing issues, and highly recommend considering Ts-rest for projects that require strong type safety.
Compiling Docs from Code:Expecting developers to manually maintain a Swagger spec works at small scale, but becomes untenable with growth. Compiling documentation directly from the code ensures accuracy, reducing discrepancies with the codebase.
Conclusion
Our journey to revamp the Snag V2 documentation was filled with challenges and learning opportunities. By embracing type safety and leveraging tools like Ts-rest, Mintlify, and Stainless, we ended up building a scalable, maintainable, and developer-friendly API documentation process. This transformation has not only enhanced our team’s efficiency but also improved the experience for our partners and developers while setting us up for growth so we can continue to meet the evolving needs of our partners.
