Customize Request Parameters

Default Behavior

By default, Speakeasy-managed SDKs require users to construct a request object to hold the parameters that an API method expects as input (for example, path, query, and so on) because explicitly stated parameters make it easier to maintain backward 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 Inline

For developers that prefer passing parameters into methods inline, you can set a threshold that Speakeasy will use to determine whether the methods in your SDK require a request object. Speakeasy will only require object construction when the number of parameters exceeds this threshold.

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 the methods in your SDK. 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 passed inline to the Get method.

Exclude Parameters From SDK

To exclude certain parameters from your generated SDK, use the x-speakeasy-ignore extension on the spec.

Here is an example using x-speakeasy-ignore: true 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
          ...

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;
}