Customize Request Parameters

Default Behavior

Speakeasy-managed SDKs will by default require users to construct a request object to hold the parameters that an API method expects as input (path, query, etc). This is the default because having parameters be stated explicitly can make it easy to maintain backwards compatibility as additional parameters are added to your API.

Example of default behavior:

    ctx := context.Background()
    req = operations.GetUserRequest(
    user_id="36ab27d0-fd9d-4455-823a-ce30af709ffc",
    )
    res, err := s.user.Get(ctx, req)
    if err != nil {
        log.Fatal(err)
    }

    if res.User != nil {
        // handle response
    }

Pass Request Parameters In-Line

Many developers prefer a more inline approach for passing parameters into methods. That is why Speakeasy allows you to set a threshold which will be used to determine whether your SDK's methods will require a request object: only when the number of parameters exceeds the threshold will object construction be required.

tip

If your API is still rapidly evolving, we recommend using this feature with caution.

In the gen.yaml file, you can use the maxMethodParams: N field in the language section to control when a request object is required to pass into your SDK's methods. For any method with less than N method parameters, construction of an object to pass into the method will be unnecessary.

Below is the same example as above, but with the maxMethodParams field set to 1.

Gen.yaml:

maxMethodParams: 1

Usage example:

    ctx := context.Background()
    res, err := s.user.Get(ctx, "36ab27d0-fd9d-4455-823a-ce30af709ffc")
    if err != nil {
        log.Fatal(err)
    }

    if res.User != nil {
        // handle response
    }

As you can see, the request object is no longer required to be constructed and passed into the method, instead the user_id value is pased inline to the Get method.

Exclude Parameters From SDK

When generating an SDK you may want to exclude certain parameters from being included in your SDK. This is can be indicated on the spec with the x-speakeasy-ignore extension.

Here is an example with an instance of x-speakeasy-ignore: true being used to remove a parameter.

paths:
  /test/user/{user_id}:
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      - name: status
        x-speakeasy-ignore: true
        in: query
        required: true
        schema:
          type: string
    get:
      operationId: getUser
      responses:
        "200":
          description: OK
          ...

Deprecate Parameters

You can deprecate parameters in your SDK by using the deprecated field in your OpenAPI schema. This will add a deprecated annotation to the corresponding field in the generated objects and remove the parameter from any relevant usage examples in the SDK docs.

paths:
  /test/user/{user_id}:
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      - name: status
        deprecated: true
        in: query
        required: true
        schema:
          type: string
    get:
      operationId: getUser
      responses:
        "200":
          description: OK
          ...

Go

type GetUserRequest struct {
    // The ID of the user
    User_ID string `pathParam:"style=simple,explode=false,name=user_id"`
    // Deprecated: this field will be removed in a future release, please migrate away from it as soon as possible.
    Status *string `queryParam:"style=form,explode=true,name=status"`
}

Python

@dataclasses.dataclass
class GetABranchPasswordRequest:
    user_id: str = dataclasses.field(metadata={'path_param': { 'field_name': 'user_id', 'style': 'simple', 'explode': False }})
    r"""The ID of the user"""
    status: Optional[str] = dataclasses.field(default=None, metadata={'query_param': { 'field_name': 'status', 'style': 'form', 'explode': True }})
    r"""The status of the user.
    Deprecated: this field will be removed in a future release, please migrate away from it as soon as possible

Typescript

export class GetUser extends SpeakeasyBase {
  /**
   * The ID of the user
   */
  @SpeakeasyMetadata({
    data: "pathParam, style=simple;explode=false;name=user_id",
  })
  user_id: string;

  /**
   * The status of the user
   *
   * @deprecated this field will be removed in a future release, please migrate away from it as soon as possible
   */
  @SpeakeasyMetadata({
    data: "queryParam, style=form;explode=true;name=status",
  })
  status?: string;
}