Feature: Standardize API Contracts Pagination and Versioning

[3m1n3nc3]

Description

Define shared DTOs, error envelopes, pagination, serialization, and API-versioning rules for every endpoint.

File Location

learnault-api/src/types/api.types.ts, learnault-api/src/middleware/, learnault-api/src/schemas/, and learnault-api/docs/API_CONVENTIONS.md

Design Reference

API Roadmap Phase 0: Standardize API Contracts Pagination and Versioning.

Dependencies

• Status: Not Blocked
• Blocked by: Feature: Define Backend Domain Module Boundaries #60
• Blocks: Feature: Complete OpenAPI and Checked-In API Documentation #71; most API Phase 1 endpoints

Tasks

• Define success, validation-error, domain-error, pagination, and request-metadata envelopes
• Choose cursor versus page pagination rules and stable ordering requirements
• Define ISO dates, exact amounts, assets, identifiers, nulls, and enum serialization
• Define request validation and unknown-field behavior
• Define /api/v1 compatibility and deprecation policy
• Add reusable schema helpers and contract tests

Acceptance Criteria

• Conventions have TypeScript types and runtime examples
• Errors have stable codes without leaking internals
• Pagination behavior is deterministic
• Contract tests pass

Verification Evidence

• Attach the conventions document and passing DTO/contract tests

Difficulty

Advanced

[Menjay7]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[Songu3020]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[Unclebaffa]

Hello Maintainer,
I'm interested in contributing to this amazing project of yours, I'm confident i will deliver the best result that aligns with this project.
Kindly assign me.
Thank you

[grantfox-oss]

🦊 GrantFox — @Unclebaffa has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #61)
2. Your PR will be reviewed by the learnault maintainers

Good luck! Track your progress on GrantFox.