Introducing Support for oneOf and anyOf in Typescript SDKs

We are introducing the special oneOf and anyOf types in our Typescript SDKs.

Details

In OpenAPI, any request parameter or response payload could use union types i.e. OneOf/AnyOf, which provides the flexibility of accepting different types of request parameters and returning various types of response payload. Here is an example of an API call using union types,

paths:
 /users/create:
    post:
      summary: Create a new user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/Accountant'
                - $ref: '#/components/schemas/Manager'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AccountantResponse'
                  - $ref: '#/components/schemas/ManagerResponse'
...

The API call, shown in the OpenApi format above, is a post-call that takes in either Accountant or Manager as request payload. Previously, union-types were not supported therefore the endpoint was expecting the combined schema UsersCreateRequest as a parameter. Here is how the parameter initialization would look like when calling the endpoint,

Before

const body: UsersCreateRequest = {
  accountId: 'A001',
  firstName: 'John',
  lastName: 'Doe',
  managerId: 'M001',
};

async () => {
    const { result, ...httpResponse } = await apiController.createUser(body);
};

After

const body: CreateUserBody = {
  accountId: 'A001',
  firstName: 'John',
  lastName: 'Doe',
};

async () => {
    const { result, ...httpResponse } = await apiController.createUser(body);
};

Now let's look at the response type of the same API call in the following example,

Before

async () => {
    const { result, ...httpResponse } = await apiController.createUser(body);
}

After

async () => {
    const { result, ...httpResponse } = await apiController.createUser(body);
    if (CreateUserResponse.isAccountantResponse(result)) {
      // Use the result narrowed down to AccountantResponse type.
    } else if (CreateUserResponse.isManagerResponse(result)) {
      // Use the result narrowed down to ManagerResponse type.
    } else {
      // Result is narrowed down to type 'never'.
    }
  };

In the above code snippet, createUser will return either the AccountantResponse or ManagerResponse instance as response payload. Previously, response was of type unknown which allowed any type of response payload. Now, with the introduction of OneOf and AnyOf support, we can check that the response can be of either AccountantResponse or ManagerResponse.

What has Changed?

The Typescript SDK now has the ability to handle union types in an endpoint's request and response. The type validation for union types is also added to support the OneOf/AnyOf constraints.

Introducing Containers

Containers are introduced in the Typescript SDK to manage union types. The union types cases are contained in a Container, and this container type comes with the validate<#CaseName> methods to validate the case values. Union-type validation and mapping/un-mapping are being handled by the schema.

Changes in Endpoints:

Endpoint Doc Changes:

The endpoint's doc string has been updated to describe union-type parameters or return types.

Before

/**
 * Create a new user
 *
 * @param body
 * @return Response from the API call
 */
async createUser(
  body: UsersCreateRequest,
  requestOptions?: RequestOptions
  ): Promise<ApiResponse<unknown>> 

After

/**
 * Create a new user
 *
 * @param body
 * @return Response from the API call
 */
async createUser(
  body: CreateUserBody,
  requestOptions?: RequestOptions
): Promise<ApiResponse<CreateUserResponse>> 

Response Deserialization:

The union-type response is container-type schema instead of unknown.

Before

return req.callAsJson(unknown(), requestOptions);

After

return req.callAsJson(createUserResponseSchema, requestOptions);

Validation Errors:

Validation errors with helpful messages will be thrown whenever an input with an invalid type is provided to an endpoint or invalid typed data is received via a response from the server. This will enforce type strictness and validation of requests and responses within the SDK. These exceptions will be thrown for:

OneOf types: When either more than one acceptable type matches or no type matches at all against the provided value.

AnyOf types: When no acceptable type matches at all against the provided value.

README Changes:

Now, the Typescript SDK README will reflect the support for union types in parameter types or response types.

Before

After

Portal Changes

We have added the capability to select and configure any case mentioned as union type through our API Code Playground on the portal. With this feature, you can now generate code samples for different cases of union types.