API Versioning Strategy

DGM is transitioning to a new API structure with versioning to provide improved organization, better backward compatibility, and clearer API paths. This page explains the current approach and the planned migration path.

Current API Structure

The current API uses identity-specific endpoints:

  • /dgm/api/funeral-home/... - Endpoints for funeral homes
  • /dgm/api/graveyard-authority/... - Endpoints for graveyard authorities

This approach has served its purpose, but as the API grows, we're moving to a more flexible and maintainable structure.

New Versioned API Structure

The new API structure uses path-based versioning with distinct version designators:

  • /dgm/api/v1/resource-name - Stable Version 1 of the API
  • /dgm/api/preview/resource-name - Preview version for features under development

Version Designators

  • v1 - Stable APIs with guaranteed backward compatibility within the version
  • preview - Unstable APIs that are still under development and may change without notice

Benefits of the New Structure

The new structure offers several advantages:

  1. Clearer domain-oriented organization - Endpoints are grouped by domain rather than identity
  2. Explicit versioning - Makes it easier to evolve the API while maintaining backward compatibility
  3. Better API lifecycle management - Enables gradual transitions when introducing breaking changes
  4. Feature preview - Allows integrators to test new features before they become stable

Migration Path

Legacy endpoints will continue to function alongside the new versioned endpoints for a period of time to allow a smooth transition:

  1. Current State - Both legacy and new versioned endpoints are available
  2. Transition Period - New functionality will primarily be added to versioned endpoints
  3. Future State - Legacy endpoints will eventually be deprecated (with advance notice)

Recommendations for API consumers:

  1. Begin migrating to the versioned API endpoints when possible
  2. For new integrations, use the versioned API endpoints
  3. Watch for deprecation notices on legacy endpoints

Warning

Many of the new versioned API endpoints are currently in preview and may change without notice. Pay attention to which ones are stable or in preview depending on your use case.

Implementation Example

Legacy endpoint:

/dgm/api/funeral-home/responsibility-statements/:id/attachment

New versioned endpoint:

/dgm/api/v1/funeral-petitions/{partyId}

The new endpoint not only follows the versioning pattern but also uses structured data rather than unstructured attachments, improving data quality and processing efficiency.