Endpoint

These CodeGen configurations manage the endpoints specific behavior in the generated SDKs.

Return Complete HTTP Response

Enable this setting to return complete HTTP response including headers and status code.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "ReturnCompleteHttpResponse": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	➖	➖

note

➖ shows that in TypeScript and Go, this behavior is inherently supported by default and cannot be disabled.

Change in SDK

Configuring this setting has the following effect on the generated SDK:

C#

Value	Change
true	public ApiResponse<Models.ServerResponse> GetData()
false (default)	public Models.ServerResponse GetData()

Java

Value	Change
true	public ApiResponse<ServerResponse> getData()
false (default)	public ServerResponse getData()

PHP

Value	Change
true	public function getData(): ApiResponse
false (default)	public function getData(): ServerResponse

Python

Value	Change
true	def get_data(): """ Returns: ApiResponse: An object with the response value as well as other useful information such as status codes and headers. """
false (default)	def get_data(): """ Returns: ServerResponse: Response from the API. """

Ruby

Value	Change
true	# @return [ApiResponse] response instance that also includes other useful information such as status codes and headers. def get_data()
false (default)	# @return [ServerResponse] response from the API call def get_data()

Use HTTP Method Prefix

You can enable this setting in case the endpoint names in your OpenAPI specification file haven't already been prefixed. Although, it is a recommended approach to prefix endpoint names while defining your OpenAPI specification. Enabling this setting will prefix the HTTP method verbs i.e. Get, Update, or Delete to the name of the methods.

note

This setting will have no effect on a method name that has already been prefixed.

Usage

To use this feature, you need to specify a Boolean type. By default, this setting is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "UseHttpMethodPrefix": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Change in SDK

Configuring this setting has the following effect on the generated SDK:

C#

Value	Change
true	try { dynamic result = await echoController.CreateJsonEchoAsync(input); } catch (ApiException e){};
false (default)	try { dynamic result = await echoController.JsonEchoAsync(input); } catch (ApiException e){};

Java

Value	Change
true	echoController.createJsonEchoAsync(input).thenAccept(result -> { // TODO success callback handler }).exceptionally(exception -> { // TODO failure callback handler return null; });
false (default)	echoController.jsonEchoAsync(input).thenAccept(result -> { // TODO success callback handler }).exceptionally(exception -> { // TODO failure callback handler return null; });

PHP

Value	Change
true	$result = $mEchoController->createJsonEcho($input);
false (default)	$result = $mEchoController->jsonEcho($input);

Python

Value	Change
true	result = echo_controller.create_json_echo(input)
false (default)	result = echo_controller.json_echo(input)

Ruby

Value	Change
true	result = echo_controller.create_json_echo(input)
false (default)	result = echo_controller.json_echo(input)

TypeScript

Value	Change
true	const { result, ...httpResponse } = await echoController.createJsonEcho(input);
false (default)	const { result, ...httpResponse } = await echoController.jsonEcho(input);

Go

Value	Change
true	apiResponse, err := EchoController.CreateJsonEcho(input)
false (default)	apiResponse, err := EchoController.JsonEcho(input)

Change in API Docs

Value	Change
true
false (default)

Encode Template Parameters

note

Please note that this is an experimental setting and it might not work as intended at all times. Feel free to contact our support if you run into an issue.

Enable this setting to encode endpoint level parameters. This change also be overridden at parameter level.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to true.

"info": {
    ...,
    "x-codegen-settings": {
        "EncodeTemplateParameters": true
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
❌	✔️	❌	✔️	✔️	✔️	❌

Validate Required Parameters

By enabling this setting, an exception will be thrown if you attempt to pass a null value to an API endpoint parameter that does not support null values. This behavior helps in investigating the SDK's behavior and identifying any issues related to null values.

note

Default values for required parameters are ignored.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "ValidateRequiredParameters": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	➖

note

➖ shows that in Go, this behavior is inherently supported by default and cannot be disabled.

Collapse Params to Array

Use this setting if you want to collapse endpoint parameters (more than 1) into an options array. This will simplify the interface of an endpoint that has a list of parameters, thus improving the overall look and feel of the generated SDKs and docs.

caution

This setting should only be used in very specific scenarios as it can hide type information from SDKs and Documentation. Please discuss your use case with the APIMatic team before enabling it.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "CollapseParamsToArray": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Change in SDK

Configuring this setting has the following effect on the generated SDK:

C#

Value	Change
true	public Models.ServerResponse PostData(Models.PostDataInput input)
false (default)	public Models.ServerResponse PostData(bool unSet, bool setToNull, string field, Models.MyData data)

Java

Value	Change
true	public ServerResponse postData(final PostDataInput input)
false (default)	public ServerResponse postData(final bool unSet, final bool setToNull, final string field, final MyData data)

PHP

Value	Change
true	public function postData(array $options): ServerResponse
false (default)	public function postData(bool $mUnSet, bool $setToNull, string $field, MyData $data): ServerResponse

Python

Value	Change
true	def post_data(self, options=dict())
false (default)	def post_data(self, un_set, set_to_null, field, data)

Ruby

Value	Change
true	def post_data(options = {})
false (default)	def post_data(un_set, set_to_null, field, data)

TypeScript

Value	Change
true	async postData({ unSet, setToNull, field, data, }: { unSet: boolean, setToNull: boolean, field: string, data: MyData, }, requestOptions?: RequestOptions ): Promise<ApiResponse<ServerResponse>>
false (default)	async postData( unSet: boolean, setToNull: boolean, field: string, data: MyData, requestOptions?: RequestOptions ): Promise<ApiResponse<ServerResponse>>

Go

Value	Change
true	type SendNumberInput struct { Number int Number1 *int } func (q *NumbersController) SendNumber( ctx context.Context, input SendNumberInput) ( models.ApiResponse[models.ServerResponse], error)
false (default)	func (q *NumbersController) SendNumber( ctx context.Context, number int, number1 *int) ( models.ApiResponse[models.ServerResponse], error)

Use Endpoint Method Name

Use the MethodName in the endpoint entity to name endpoints instead of the Name property. This feature is useful when you are unable to modify the API specification file, yet still want a different endpoint name reflected in the generated docs and SDKs than what has been originally mentioned in the specification file.

UseEndpointMethodName has a global affect on the endpoint naming, meaning that once you enable this, it will be automatically reflected in all endpoints.

You can use the methodName property in x-operation-settings to configure a string value for a method name at endpoint level. Refer to Operation settings for more details.

note

Please note that this is an experimental setting and we might remove support of this in the future. Feel free to contact our support if you run into an issue.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "UseEndpointMethodName": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	❌	❌	✔️	✔️

Nullify 404

In certain APIs, the extensive use of the 404 status code is used to indicate the absence of a particular item. However, this can cause confusion as to whether it signifies an error or simply denotes a missing value.

To address this confusion, we have incorporated both options in our SDKs. By default, when this setting is set to false, the SDK will adhere to the HTTP protocols and throw an exception. When the setting is enabled, the SDK returns null response on the HTTP status code 404 instead.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "Nullify404": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	❌	❌

Nullify Empty Responses

In certain APIs returning multiple responses, an empty payload can also be defined along with other non-empty responses. Check out the following example:

post:
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SuccessResponse"
    "201":
      description: Created

When the setting is enabled, SDKs will accept the empty responses as null, and non-empty response as SuccessResponse i.e. defined in 201 and 200 statusCodes in the above example.

This setting is disabled by default which allows the endpoints in SDK to return only the SuccessResponse i.e. defined in 200 statusCode in the above example.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "NullifyEmptyResponses": true
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Lift Parameter Description From Custom Type

Enable this setting to use a custom type's description as parameter description when a parameter referencing has missing description.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "LiftParameterDescriptionFromCustomType": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Change in API Docs

Here is a snippet from an OpenAPI specification file:

{
    "Name": "Boss",
      "BaseType": "Employee",
      "ImplementationType": "Structure",
      "Description": "",
      ...
}

Here, Employee is a custom type defined as:

"CustomTypes": [
    {
      "Name": "Employee",
      "Description": "This is a custom type defined for all employees",
    }
]

Here's how the API docs change according to how LiftParameterDescriptionFromCustomType is configured:

Value	Change
true
false (default)

Force Keyword Arguments in Ruby

This setting determines whether to use keyword arguments or positional arguments for required parameters in Ruby SDKs. Enabling this setting means code generator will utilize keyword arguments, and if disabled, the code generator uses positional arguments.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "ForceKeywordArgsInRuby": false
    }
}

Language Support

This setting only applies to Ruby SDKs.

Change in SDK

Configuring this setting has the following effect on the generated SDK:

Value	Change
true	result = echo_controller.json_echo(input: input)
false (default)	result = echo_controller.json_echo(input)