Skip to main content

Releasing Endpoints (Beta → Stable)

This document describes the process for promoting Flow API endpoints from beta to stable status. It serves as both an internal checklist and transparency for developers building on the API.

Stability Classifications​

See API Stability for full definitions of:

  • Stable - Production-ready, backward compatibility guaranteed
  • Beta - Functional but may change without notice
  • Private - Internal only, not for external use

Promotion Checklist​

Before an endpoint can be promoted from beta to stable, it must satisfy all of the following criteria:

1. Contract Finalized​

  • Request schema is locked (no breaking changes planned)
  • Response schema is locked (no breaking changes planned)
  • All required fields are documented
  • All optional fields are documented with defaults
  • Field types match implementation

2. Error Handling Complete​

  • All error codes are documented
  • Error response format follows standard envelope
  • Validation errors include field-level details
  • Edge cases return appropriate errors (404, 403, etc.)

3. SDK Support​

  • TypeScript SDK includes the endpoint
  • TypeScript SDK types are generated and accurate
  • Python SDK support (can follow initial release)
  • Go SDK support (can follow initial release)

4. Documentation Complete​

  • Reference page created with full endpoint details
  • curl examples for all operations
  • SDK examples for all operations
  • Common errors section
  • Added to OpenAPI spec (stable version)

5. Troubleshooting Entry​

  • FAQ/troubleshooting entry for common issues
  • Error resolution steps documented
  • Links to related documentation

6. Production Tested​

  • Endpoint has been used in real workloads
  • Performance is acceptable under load
  • No critical bugs reported
  • Monitoring and alerting in place

7. Review and Approval​

  • Code review completed
  • Documentation review completed
  • Stability review completed
  • Changelog entry prepared

Promotion Process​

  1. Candidate Identified - Engineering or PM identifies beta endpoint ready for promotion
  2. Checklist Completed - All items above must be satisfied
  3. Documentation PR - Create PR adding endpoint to stable docs and OpenAPI
  4. Review - PM/Engineering review the promotion
  5. Merge - PR merged, endpoint is now stable
  6. Announce - Changelog updated, developers notified

Backward Compatibility Promise​

Once an endpoint is stable, we guarantee:

  • No removal without 6-month deprecation notice
  • No removal of response fields without deprecation period
  • No change to the meaning of existing fields
  • Additive changes only (new optional fields, new optional parameters)

Deprecation Process​

If a stable endpoint needs to be deprecated:

  1. Announce - Add deprecation notice to docs and changelog
  2. Warning Headers - Add Deprecation header to responses
  3. Migration Guide - Publish migration guide to replacement
  4. Timeline - Minimum 6 months before removal
  5. Remove - Remove endpoint and update docs

Beta Endpoint Guidelines​

Beta endpoints should:

  • Be marked clearly as beta in any documentation
  • Not be included in the stable OpenAPI spec
  • Not be included in the primary sidebar navigation
  • Include a warning about potential changes

Questions?​

For questions about endpoint stability or promotion, contact support@flowsocial.app.