[Smithy Framework] - Extend our Smithy Framework to Customers Create API and its corresponding Request/Response Payloads

[Debarshi-Gupta]

Summary

Extend our Smithy Framework to Customers Create API, an existing Hyperswitch API and its Request/Response Payloads.

Type

Feature

Context

What is the Smithy Framework?

Smithy is an Interface Definition Language (IDL) and set of tools created by Amazon for building APIs and SDKs. Think of it as a way to describe your API's structure, data types, and operations in a language-agnostic format, then automatically generate client SDKs, server stubs, documentation, and validation code for multiple programming languages.

1. Rust-to-Smithy Code Generation Pipeline

Instead of writing Smithy models manually, you've created a system that automatically generates them from your existing Rust code. This is brilliant because:

• You maintain your source of truth in Rust
• Smithy models are automatically kept in sync
• You can generate SDKs for other languages from your Rust types

2. The Three-Crate Architecture

smithy crate: Contains the #[derive(SmithyModel)] macro that you annotate your Rust structs/enums with.

smithy-core crate: Contains the core types and logic for:

• Representing Smithy models in Rust
• Converting Rust types to Smithy shapes
• Generating the actual Smithy IDL files

smithy-generator crate: A build-time tool that:

• Scans your entire workspace for types with #[derive(SmithyModel)]
• Collects all the generated models
• Outputs .smithy files

3. How the Attribute System Works

Your implementation requires the #[smithy(value_type = "...")] attribute on each field. This is crucial because:

• Explicit Type Mapping: Rust types don't always map 1:1 to Smithy types, so you specify exactly how each field should be represented
• Field Filtering: Fields without this attribute are ignored, giving you fine-grained control
• Validation: You can add constraints like pattern, range, length, etc.

Example usage from your codebase:

#[derive(SmithyModel)]
#[smithy(namespace = "com.hyperswitch.smithy.types")]
pub struct CustomerDetails {
    #[smithy(value_type = "String")]
    phone_country_code: String,
    
    #[smithy(value_type = "String")]
    email: String,
    
    #[smithy(value_type = "String", required)]
    id: String,
    
    // This field will be ignored in Smithy generation
    internal_field: HashMap<String, String>,
}

4. The Generation Process

I can see from your workspace that you have 65 structs/enums with #[derive(SmithyModel)] across various crates:

1. Build Time: The build.rs script scans your workspace for #[derive(SmithyModel)] annotations
2. Model Collection: Each annotated type generates a SmithyModel containing shapes, constraints, and metadata
3. IDL Generation: The generator creates .smithy files in the smithy/models/ directory
4. SDK Generation: These .smithy files are then used with standard Smithy tooling to generate client SDKs

Starter tasks

1. Add the derive macro to your struct:

   #[derive(SmithyModel)]
   pub struct YourStruct {
       // fields here
   }

2. Add the namespace attribute (choose one approach):

   #[derive(SmithyModel)]
   #[smithy(namespace = "com.hyperswitch.your.namespace")]
   pub struct YourStruct {

3. Add value_type attributes to each field you want in the Smithy model:

   #[derive(SmithyModel)]
   #[smithy(namespace = "com.hyperswitch.your.namespace")]
   pub struct YourStruct {
       #[smithy(value_type = "String")]
       pub name: String,
       
       #[smithy(value_type = "i64")]
       pub amount: i64,
       
       #[smithy(value_type = "Option<String>")]
       pub optional_field: Option<String>,
       
       // This field will be IGNORED (no smithy attribute)
       internal_field: HashMap<String, String>,
   }

4. Add constraints (optional but recommended):

   #[derive(SmithyModel)]
   #[smithy(namespace = "com.hyperswitch.your.namespace")]
   pub struct YourStruct {
       #[smithy(value_type = "String", required)]
       pub id: String,
       
       #[smithy(value_type = "String", pattern = "^[a-zA-Z0-9]+$")]
       pub code: String,
       
       #[smithy(value_type = "i64", range = "1..=1000")]
       pub amount: i64,
       
       #[smithy(value_type = "String", length = "1..=255")]
       pub description: String,
   }

We are enhancing the Smithy framework by adding support for the Customers Create API. This means annotating the request and response structs for this API with the Smithy macros so that the generator produces the corresponding .smithy models. This keeps our API definitions consistent, allows SDKs to include customer creation, and brings the Customers Create flow in line with other APIs like Payments Create.

Implementation hints

Refer to Payments Create API and its corresponding Request/Response Payloads, follow the same logic, how it is implemented for the API calls and how the Request/Response payloads are annotated for those APIs.

Acceptance criteria

• All types and nested types present in Request/Response payloads must be annotated appropriately.
• Run cargo build on the project to ensure that no compilation issue exists.
• No change in existing business logic or functionality.
• Run smithy validate to ensure that the Smithy Models generated from the annotated Rust structs are accurate.

Contribution Guidelines:

• Fork the repository and create a new branch for your work.
• Write clean, well-documented code with clear commit messages.
• Run formatter, and make sure that your code is properly formatted.
• Make sure to follow our coding standards and contribution guidelines.

---

Resources:

• Link to the Smithy Framework PR: Smithy Framework PR
• Link to the API endpoint specifications: API Docs

Submission Process:

• Ask the maintainers for assignment of the issue, you can request for assignment by commenting on the issue itself.
• Once assigned, submit a pull request (PR).
• Maintainers will review and provide feedback, if any.
• Maintainers can unassign issues due to inactivity, read more here.
• For this issue, please submit a PR on @juspay/hyperswitch repo, and link it to the issue.

Refer here for Terms and conditions for the contest.

If you have any questions or need help getting started, feel free to ask in the comments!

Mentor contact

@Debarshi-Gupta

Pre-flight

• I read the Contributing Guide and setup
• I searched existing issues