Beta APIs are subject to change and may be deprecated in future versions. These endpoints are being transitioned to stable v2 APIs. Please plan to migrate to the corresponding v2 endpoints when available.
What are Beta APIs?
Beta APIs in the Zitadel Ruby SDK provide access to endpoints that are in the v2beta version namespace. These APIs represent features and functionality that are:
- Tested but evolving: The APIs are functional and tested, but the interface may change based on feedback and evolving requirements
- Subject to breaking changes: Unlike stable APIs, beta APIs may introduce breaking changes in minor or patch releases
- Transitional: Most beta APIs have corresponding stable v2 versions in development or already available
Stability Guarantees
What to Expect
- Functional: Beta APIs are production-ready and fully functional
- Documented: Comprehensive documentation is provided for all beta endpoints
- Supported: Issues and bugs are addressed through normal support channels
- Deprecation notices: Clear warnings are provided when endpoints will be removed
What Not to Expect
- API stability: Method signatures, request/response formats may change
- Long-term support: Beta APIs will be removed in future major versions
- Backward compatibility: Updates may require code changes in your application
Available Beta Services
The following beta services are available in the Zitadel Ruby SDK:
How to Access Beta Services
Initialize the Client
require 'zitadel_client'
# Configure the client
Zitadel::Client::Api.configure do |config|
config.host = 'your-instance.zitadel.cloud'
config.access_token = 'YOUR_ACCESS_TOKEN'
end
# Initialize a beta service
user_service = Zitadel::Client::Api::BetaUserServiceApi.new
Example Usage
# Create a request object
request = Zitadel::Client::BetaUserServiceAddHumanUserRequest.new(
username: '[email protected]',
profile: {
first_name: 'John',
last_name: 'Doe'
},
email: {
email: '[email protected]',
is_verified: false
}
)
# Call the beta API
begin
response = user_service.add_human_user(request)
puts "User created: #{response.user_id}"
rescue Zitadel::Client::ApiError => e
puts "Error: #{e.message}"
end
Migration Path to Stable APIs
Deprecation Timeline
- Beta Release: API is available in beta namespace (
v2beta)
- Stable Release: Corresponding v2 API becomes generally available
- Deprecation Notice: Beta API is marked deprecated (6-12 months notice)
- Removal: Beta API is removed in next major version
Migration Strategy
1. Identify Stable Alternatives
Check the deprecation warnings in each beta endpoint’s documentation for the corresponding v2 endpoint:
# Beta (deprecated)
response = beta_user_service.add_human_user(request)
# Stable alternative
response = user_service_v2.add_human_user(request)
2. Test in Development
Before migrating production code:
- Test the v2 endpoint with your use cases
- Verify response structure matches your expectations
- Check for any behavioral differences
3. Update Gradually
Migrate endpoints incrementally:
# Feature flag approach
def create_user(user_data)
if use_v2_api?
user_service_v2.add_human_user(user_data)
else
beta_user_service.add_human_user(user_data)
end
end
4. Monitor for Issues
After migration:
- Monitor error rates
- Validate response data
- Check performance metrics
Best Practices
When Using Beta APIs
- Plan for Migration: Track which beta APIs you use and monitor for stable releases
- Handle Errors Gracefully: Beta APIs may have more edge cases
- Stay Updated: Regularly update the SDK to get latest improvements and fixes
- Test Thoroughly: Beta APIs may have undocumented behavior
- Read Deprecation Notices: Always check documentation for migration guidance
Error Handling
begin
response = beta_service.method_call(request)
rescue Zitadel::Client::ApiError => e
case e.code
when 400
# Bad request - check your parameters
when 401
# Unauthorized - check your access token
when 404
# Resource not found
when 500
# Server error - retry with backoff
else
# Handle other errors
end
# Log full error details
Rails.logger.error "Zitadel API Error: #{e.message}"
Rails.logger.error "Response body: #{e.response_body}"
end
Support and Resources
This documentation covers beta APIs in SDK version 1.0.0. Check the changelog for updates and migration guides.
