TL;DR;
Schema-first development, despite its advantages, hasn’t become mainstream. We’ve been optimizing it for centralized, public APIs. Fortunately, API Genie adapts this workflow for mainstream scenarios (internal APIs developed by independent, cross-functional teams), while preserving its benefits.
Introduction
API development is crucial in modern software architecture.
Approaches to development of RESTful APIs
When developing RESTful APIs, four main approaches are available: schema-less, code-first, schema-first, and design-first. Let’s review each, discussing their advantages and weaknesses.
Schema-less
Developers don’t create a formal API contract. They start coding after collecting business requirements.
Advantages:
- Rapid prototyping
- Flexibility
Weaknesses:
- Lack of standardisation
- Absence of documentation
Best for:
- Early-stage projects with evolving requirements. Rules of thumb: less
than 3 developers, excellent communication, less than 10 simple
endpoints, no external clients, no changes.
Code-first
The API contract is created from backend code. Annotations are often used to generate the contract.
Advantages:
- Familiar to developers
- Immediate testing
- Easier integration with existing codebases
Weaknesses:
- Tightly coupled design
- Inconsistency across services or teams
- Not all technologies and frameworks have good support for contract generation
Best for:
- Internal APIs and teams prioritizing rapid feature development.
Schema-first
A formal contract serves as the single source of truth. The API implementation must conform to the contract.
Advantages:
- Clear contract between teams.
- Consistency across services and teams.
- Automated code generation and documentation.
Weaknesses:
- Requires upfront planning and design.
- Perceived as slowing initial development.
- Requires additional tooling and processes.
Best for:
- Large-scale APIs with multiple consumers.
- Organizations with separate frontend and backend teams.
- Projects where long-term maintainability is a priority.
Design-first
Similar to schema-first, but with more emphasis on design. Advanced mocking and testing enable high-quality API development without writing code.
Advantages:
- Promotes thoughtful API design.
- Improves API quality and user experience.
- Facilitates early feedback.
Weaknesses:
- More time-consuming than the others, especially for smaller projects.
- Requires strong design skills.
- May lead to over-engineering.
Best for:
- Public APIs and organizations prioritizing user experience.
- Organizations with dedicated API design teams.
- Projects where API consistency and user experience are critical.
Challenges of Schema-first Approach
Despite its advantages, schema-first hasn’t become mainstream. Why?
- Optimized for the wrong scenario:
- Current focus: Centralized organizations, cloud-based tools
- Needed focus: Small, cross-functional teams with local development
- Migration difficulties:
- Creating initial contract
- Gradual migration strategies
- Code generation issues:
- Handling repeated generation after schema changes
- Preserving custom code during regeneration
- Schema consistency:
- Maintaining uniformity across the organization
- Handling schema versioning
How API Genie is different
API Genie addresses these challenges by:
- Supporting both local and centralized development
- Providing minimal setup and environment
- Offering migration tools for existing applications
- Simplifying schema changes
- Encouraging iterative design and development
Stay tuned for our upcoming series exploring API Genie’s modules in depth.
