<aside> 🤷🏽 This is all very much a work in progress, and research is constantly ongoing. If you have any suggestions, or are able to refer to any established practices or terminology, please let me know!
</aside>
<aside> 🧠This should all be easy enough to understand, but see also Glossary for a breakdown of the terms we use. We’re trying to be specific and consistent with their application.
</aside>
This page serves to document the underlying motivations for our ideas, and why we believe it’s worth upending the status quo. It’s a mouthful, but if you indulge us, we hope you’ll reach the same conclusions we did.
Web APIs are the backbone of the modern world. Over the years, a number of methodologies and technologies have emerged, such as the ubiquitous-in-name-only REST and the rising star GraphQL. These are supplemented by numerous tools - documentation systems like OpenAPI, test clients like Postman, and numerous software libraries promising to ease the burden of implementation for clients and servers.
However, I believe there’s a sweet spot between flexibility, longevity, and convenience that the current API ecosystem comes tantalizingly close to reaching. What we need is a cohesive system with a flexible methodology that brings the best of these worlds together.
With this project, I hope to revolutionize web development by making robust, principled API design simple and easily accessible to everyone.
This project started out small, but in pursuit of that goal I grappled with shortcomings in the rest of the greater API development ecosystem that inspired me to rethink the whole thing top to bottom. A project of this scope requires robust justification, which I attempt to outline below.
The general concept of Veneto APIs is to couple the client and server with respect to the data that’s transferred, while decoupling the rest of the interface as much as possible. This is the minimum necessary extent to facilitate the flexibility we’re after. Bear with us, you’ll see what we mean.
Veneto exists to promote comprehensive, flexible domain modeling. We believe our principles drive robust design decisions and promotes a fluid developer experience down the line. Developing an entire ecosystem of tools from scratch gives us a unique opportunity to extract common patterns so that they can be expressed elegantly and concisely.
Veneto is also a documentation tool. In tandem with a comprehensive domain model, which serves as powerful documentation in its own right, users will be able to add comments wherever they need to in order to convey important information.
This will be completely uncontroversial to most developers, but as a matter of pretext: Veneto is designed to operate with statically-typed data structures, just like most popular APIs.
Having a well-defined schema is what makes an API flexible in its use cases - the client knows exactly what it can send to and receive from the server, and it can do anything it chooses with that information. Data types are a first class citizen in Veneto domain models, easy to create, understand, and manipulate.
<aside> đź’ˇ The most notable philosophy that contradicts this idea is REST; coupling the client to the server by data schema is far and away the most violated constraint of ostensibly-RESTful APIs. Veneto is not REST, nor does it claim to be - we aim to solve a different set of problems at a different time scale.
</aside>
We are firm believers in type safety. Rust and Swift have magnificent type systems, and TypeScript has made massive improvements in the development experience for JavaScript applications and their ease of maintenance. We want to encourage these principles however we can, both in domain modeling and development tools.
The biggest difference between the two camps above concerns sum types & monadic optionals. We believe in the rigor and expressive power of sum types, and are actively considering ways to formalize those ideas in API domain models.