DID Method Routing

DID method routing is how the Vidos resolver service allows you to work with many different types of Decentralized Identifiers (DIDs) through a single, consistent API. Instead of implementing separate resolution logic for each DID type, you can rely on the resolver to handle the complexities of different methods.

What is DID Method Routing?

When you integrate with decentralized identity systems, you’ll encounter many DID methods - from cryptographic (did:key, did:jwk) to blockchain-based (did:ethr, did:ion) to web-based (did:web). Each has unique characteristics and resolution requirements.

flowchart LR
    A[Your Application] --> B[Resolver API]
    B --> C{DID Method Router}
    C -->|did:key| D[Key Resolver]
    C -->|did:web| E[Web Resolver]
    C -->|did:ethr| F[Ethereum Resolver]
    C -->|did:ion| G[ION Resolver]
    D & E & F & G --> H[Standardized Response]
    H --> A

DID method routing provides you with:

1. A unified API endpoint for all DID methods, simplifying your integration code
2. Method-specific processing that handles the unique requirements of each DID type behind the scenes
3. Consistent response formats that follow the W3C DID Resolution specification, regardless of which method you’re resolving
4. Configurable method support allowing you to enable only the methods your application needs

This approach lets you focus on using DIDs in your application without implementing separate resolution logic for each method you want to support.

How the API Processes Your DID Request

When you send a DID to the resolver API, the first step identifies which method you’re trying to resolve:

flowchart TD
    A["Your request: did:key:z6Mk..."] --> B["Extract DID method"]
    B --> C["Identify method as 'key'"]
    C --> D["Check if method is supported"]
    D --> E["Verify method is enabled in config"]
    D -.-> F["Available Methods:
        - key
        - web
        - ethr
        - ion
        - ..."]
    E -.-> G["Method Configuration:
        key: enabled
        web: enabled
        ethr: enabled
        ..."]
    E -->|Success| H["Continue with resolution"]
    E -->|Failure| I["Return appropriate error"]

This validation ensures that:

1. The system recognizes the method part of your DID (the segment after “did:”)
2. The resolver configuration enables the method

If you use an invalid or disabled method, you’ll receive a clear error methodNotSupported. This check happens before any method-specific processing begins, providing quick feedback on basic validation issues.

You can control DID methods through configuration, enabling or disabling specific methods based on your requirements. For details on configuring methods, see the Method Configuration documentation.

The Resolver Architecture

The resolver service uses a layered architecture that separates the API interface from the method-specific resolution logic:

flowchart TD
    subgraph "API Layer"
        A[DID Resolution API] --> B[Method Routing]
    end

    subgraph "Resolution Layer"
        B --> C{Method Dispatcher}
        C --> D[Method Configuration]
    end

    subgraph "Method Implementations"
        C -->|did:key| E[Key Resolution]
        C -->|did:web| F[Web Resolution]
        C -->|did:ethr| G[Ethereum Resolution]
        C -->|did:...| H[Other Methods]
    end

    subgraph "Response Formatting"
        E --> I[Result Formatter]
        F --> I
        G --> I
        H --> I
        I --> J[Standardized Response]
    end

This architecture offers several advantages from an API consumer’s perspective:

1. Unified Interface: You can resolve all method types through a single API endpoint
2. Method Abstraction: The architecture hides the complexity of different DID method implementations behind a consistent interface
3. Declarative Configuration: You can enable or disable methods through configuration without changing the API
4. Standardized Responses: The resolver follows the W3C DID Resolution specification format (v1.0) regardless of which method you use

This design allows your applications to work with different DID methods using the same code path, while the resolver service handles the method-specific details internally.

Resolution Process

When you resolve a DID through the API, your request goes through these steps to produce a standardized response:

sequenceDiagram
    participant You as Your Application
    participant API as Resolver API
    participant Processing as Method Processing
    participant Format as Response Formatting

    You->>API: Send DID resolution request
    Note over API: Example: GET /w3c/did/1.0/identifiers/did:key:z6Mk...

    API->>API: Extract method ("key")
    API->>API: Check if method is supported and enabled

    API->>Processing: Process method-specific resolution
    Note over Processing: Different for each method type
    Processing-->>API: Return resolution data

    API->>Format: Format to standard W3C structure
    Format-->>API: Prepare final response

    API-->>You: Return DID Document (or error)

This process offers several advantages for your application:

1. Consistent Interface: You use the same API endpoint and pattern for all DID types
2. Standardized Responses: You always receive responses in the same format regardless of the underlying DID method
3. Transparent Error Handling: When something goes wrong, you receive clear error codes with consistent structure
4. Content Negotiation: The API formats responses based on your preferred content type

This approach eliminates the need for your code to implement different resolution logic for each DID method you want to support, significantly simplifying integration.

For a comprehensive list of supported DID methods and their specific capabilities, see the Supported DID Methods.

Error Handling

The resolver handles various error conditions consistently:

flowchart TD
    A["DID Resolution Request"] --> B{"Parse DID"}
    B -->|Success| C{"Method Supported?"}
    B -->|Failure| D["invalid_did"]
    C -->|Yes| E{"Method Enabled?"}
    C -->|No| F["method_not_supported"]
    E -->|Yes| G{"Resolver Available?"}
    E -->|No| H["method_not_enabled"]
    G -->|Yes| I{"Resolution Process"}
    G -->|No| J["internal_resolver_error"]
    I -->|Success| K["Return DID Document"]
    I -->|Failure| L["method_specific_error"]

    D --> M["Convert to Standard Error Response"]
    F --> M
    H --> M
    J --> M
    L --> M

    M --> N["Return Error with Appropriate HTTP Status"]

This standardized approach ensures that your applications receive consistent error responses regardless of which DID method you try to resolve.

Always implement proper error handling in your application code to gracefully handle resolution failures. The standardized error responses help you detect and respond to specific error conditions.

Integration with Other Vidos Services

The resolver’s method routing capability enhances your ability to work with other components in the Vidos ecosystem:

• Verification Workflows: When you use the Verifier service, the resolver automatically fetches the right cryptographic material needed for validation, regardless of which DID method you used
• Flexible Configuration: You control which methods are available through instance configuration, enabling only what your application needs
• Standard Compliance: The resolver follows the W3C DID Resolution specification, ensuring compatibility with other standards-compliant tools
• Resource Access: When you use DID URL dereferencing to access resources linked to DIDs, the routing system handles the complexities of different method behaviors

By leveraging these integrations, you can build powerful verification workflows without implementing the intricacies of each DID method’s resolution process.

Conclusion

DID method routing enables you to resolve multiple types of DIDs through a single consistent API. You benefit from:

• A unified interface for resolving any supported DID method
• Standardized responses that follow the W3C specification regardless of method
• Clear, consistent error handling across all methods
• The ability to configure which methods are available in your environment

This approach simplifies your application code by eliminating the need to implement method-specific handling, while still providing the flexibility to work with a wide range of DID methods as your requirements evolve.