Skip to main content

Introducing Support for oneOf and anyOf in Ruby SDKs

· 5 min read

We are introducing the special oneOf and anyOf types in our Ruby 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,

body = Accountant.new(
  'accountantId',
  'john',
  'doe'
)

response = client.user.create_user(body)

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

response = client.user.create_user(body)

assert response.instance_of? AccountantResponse # true
assert response.instance_of? ManagerResponse # false

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

What has Changed?​

The Ruby 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 UnionTypeLookUp​

All instances of union types (i.e. OneOf/AnyOf) instances that are defined in the spec are now being accessed through UnionTypeLookUp. We introduced a class in utilities by the name of UnionTypeLookUp which holds a hash of unionTypes. The responsibility of the UnionTypeLookUp class is to provide the already in-place union-type instances. The instance returned by the UnionTypeLookUp class, is then used for validation, deserialization, and serialization.

For the above endpoint, the union-type instance would look like,

{
    :CreateUserBody => AnyOf.new(
      [
        LeafType.new(Accountant),
        LeafType.new(Manager)
      ]
    ),

    :CreateUserResponse => OneOf.new(
      [
        LeafType.new(AccountantResponse),
        LeafType.new(ManagerResponse)
      ]
    )
}

Changes in Models​

Now, any custom type (i.e. models or enums) participating as union-type, has the validate method to verify all required properties are present in the case of models and the provided value is a valid enum value in the case of enums.

Changes in Endpoints​

Endpoint Doc Changes​

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

# Create a new user
# @param [UsersCreateRequest] The user instance to create.
# @return [AccountantResponse | ManagerResponse] The created user.
def create_user(body)

end

Parameter Validation​

The union-type parameters are now being validated when sending the request.

new_api_call_builder
   .request(new_request_builder(HttpMethodEnum::POST,
                                  '/users/create',
                                  Server::DEFAULT)
                .body_param(new_parameter(body)
                            .validator(proc do |value|
                              UnionTypeLookUp.get(:CreateUserBody)
                                              .validate(value)
                            end))
                .body_serializer(proc do |param| param.to_json unless param.nil? end))
   .execute

Response Deserialization​

The union-type response is now being validated and then deserialized.

new_api_call_builder
   .response(new_response_handler
                .deserializer(proc do |response, should_symbolize|
                  APIHelper.deserialize_union_type(
                    UnionTypeLookUp.get(:CreateUserResponse),
                    response, should_symbolize, true
                  )
                end))
   .execute

Validation Exceptions​

We have introduced OneOfValidationException and AnyOfValidationException which 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 feature will enforce type strictness and validation of requests and responses within the SDK.

Following are the trigger points for raising these exceptions:

OneOfValidationException: It is raised when either more than one type is matched or no type is matched at all against the provided value.

AnyOfValidationException: It is raised when no type matches at all against the provided value. You can explicitly rescue the OneOfValidationException and AnyOfValidationException in the code snippet.

begin
  result = client.user.create_user(accountantOrManager)
  puts result
rescue OneOfValidationException => e
  puts "Caught OneOfValidationException: #{e.message}"
rescue AnyOfValidationException => e
  puts "Caught AnyOfValidationException: #{e.message}"
rescue APIException => e
  puts "Caught APIException: #{e.message}"
end

README Changes​

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

readme endpoint after

Portal Changes​

We have added the capability to select and configure any of the cases 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.

portal2