Using Optional and Nullable Properties in API Requests

An essential part of an API endpoint is its parameters. While certain parameters must be included in each request, there may be some parameters that may or not may not be included in the request. The optional property was introduced to create unique combinations of such parameters in API requests. In other cases, some parameters may be allowed to hold a null value, which is catered via nullable properties that help in coping with the errors if null is not handled correctly.

While all endpoint parameter types (query, body, form, and path) can have optional nullable properties, we’ll focus on the optional nullable properties of a model’s fields being passed as request parameters in a client SDK.

This blog is the first part of a series on how optional and nullable properties can be used flexibly and in multiple combinations to cater to each parameter of your API requests.

Required, Optional, and Nullable Properties in OpenAPI

The OpenAPI Specification is a simple yet powerful way of describing RESTful APIs, in a machine and human-readable format, using JSON or YAML. OpenAPI has some examples of Uber’s API listed in their repository to help understand how the endpoint is specified with OpenAPI.

The OpenAPI specification allows defining parameters for an operation or path. Parameters can be of different types i.e. header, query, cookies, path parameters.

Required Parameters

One of the attributes that can be defined for these parameters is “required” which simply means whether it is a required parameter or an optional one. Let's take a look at an example of Uber’s Get Products endpoint specification:

You can get more details regarding Required and Optional Parameters in the official OAS document.

Nullable Parameters

OpenAPI supports values of data types to be null. To specify, one can use the “nullable: true” property while defining a data type in OAS version 3.0.0. Let's look at the definition of the Profile schema that is defined for the response that we receive for the endpoint User Profile. The attribute promo_code is nullable here:

For more details, please refer to the Null Property section in the OAS document.

Optional and Nullable Properties in APIMatic's Client SDKs

APIMatic is a developer experience platform that focuses on increasing your API’s adoption with comprehensive documentation, multi-language SDKs, and much more. The SDKs are autogenerated for your API and contain support for optional and nullable properties, that are translated from your OpenAPI specification file.

The client SDK is built up of a multitude of endpoints sending data from client to server with the help of parameters. Those parameters can be sent in different parts of a request and hence they are distinguished on the location in which they are sent. Endpoint parameters can be of four types:

1. Query parameters
2. Path parameters 
3. Body parameters
4. Form parameters

These parameters can have multiple properties associated with them like their schema, description, summary, and more. Required and nullable are two of those properties that can be set for these parameters.

During client and server communication, data is serialized from an object to a JSON string and gets deserialized from a JSON string to an object. The data being passed in the parameters can be a simple field, or a model containing multiple fields. Model fields can have required and nullable properties in the same way as a request parameter itself. Regardless of the type of data being passed, optional and nullable is in context to the representation of that data in JSON string during serialization.

An optional property means that it may or may not be present in the resultant JSON string, while a required property means that it will always be present in the JSON string. Nullable means that if the property is present in JSON, it can hold a null value and non-nullable means that the value of that property cannot be null in the JSON string. Therefore, we can formulate a total of four combinations for this:

1. Optional Nullable

If a field (whether it is a parameter or a part of a model) is uninitialized, i.e., not specified, then it should be ignored in the JSON string during serialization. If it is initialized and assigned a null value explicitly, then it should be represented in the JSON string.

Let's consider the example of a model/definition Profile which consists of the following fields:

Its OpenAPI specification looks like this:

During the instantiation of Profile, if   promo_code  is initialized with a null value in the client SDK and sent in the request, the resultant JSON string after serialization will hold its null value as its nullable property:

{
    "picture": "https://d1w2poirtb3as9.cloudfront.net/f3be498cb0bbf570aa3d.jpeg",
    "first_name": "Uber",
    ...
    "mobile_verified": true,
    "promo_code": "null"
}

{
    "picture": "https://d1w2poirtb3as9.cloudfront.net/f3be498cb0bbf570aa3d.jpeg",
    "first_name": "Uber",
    ...
    "mobile_verified": true,
}

{
    "picture": "https://d1w2poirtb3as9.cloudfront.net/f3be498cb0bbf570aa3d.jpeg",
    "first_name": "Uber",
    ...
    "mobile_verified": true,
    "promo_code": "uberd340ue"
}

2. Optional Non-Nullable

Suppose a field (whether it’s a parameter or a part of the model) is uninitialized, i.e., not specified. In that case, it should be ignored in the JSON string during serialization but as it can not be initialized with a null value, hence we should ignore it in JSON. Let’s look at the Profile JSON schema again, where the attribute picture  is optional non-nullable as specified in the OAS of Profile.

If picture is initialized with a non-null value when sending it in a request, the resultant JSON string will look like this:

{
    "picture": "https://d1w2poirtb3as9.cloudfront.net/f3be498cb0bbf570aa3d.jpeg",
    "first_name": "Uber",
    "middle_name": "null",
    "last_name": "Developer",
    "uuid": "f4a416e3-6016-4623-8ec9-d5ee105a6e27",
     ...
}

{
    "first_name": "Uber",
    "middle_name": "null",
    "last_name": "Developer",
    "uuid": "f4a416e3-6016-4623-8ec9-d5ee105a6e27",
     ...
}

3. Required Nullable

Required Nullable attributes will always become part of the resultant JSON string as they are required. It will always be included in the JSON, whether it has a null or non-null value. Let's consider the middle_name  as a required nullable attribute.

If middle_name  is initialized with a null value or uninitialized in the request, its JSON output will be:

{
   ...
    "middle_name": "Software",
    "last_name": "Developer",
    "uuid": "f4a416e3-6016-4623-8ec9-d5ee105a6e27",
   ...
}

{
    ...
    "middle_name": "faloola",
    "last_name": "Developer",
    "uuid": "f4a416e3-6016-4623-8ec9-d5ee105a6e27",
    ...
}

4. Required Non-Nullable

Required Non-Nullable attributes are also a must in JSON string during serialization. A null value is not allowed to be specified as required so it cannot be ignored.

The rider_id  is a non-nullable attribute in the Profile schema. The null value cannot be specified in this case, and with a non-null value its resultant JSON will be:

{
    "picture": "https://d1w2poirtb3as9.cloudfront.net/f3be498cb0bbf570aa3d.jpeg",
    "first_name": "Uber",
    "middle_name": "null",
    "last_name": "Developer",
    "uuid": "f4a416e3-6016-4623-8ec9-d5ee105a6e27",
    "rider_id": "8OlTlUG1TyeAQf1JiBZZdkKxuSSOUwu2IkO0Hf9d2HV52Pm25A0NvsbmbnZr85tLVi-s8CckpBK8Eq0Nke4X-no3AcSHfeVh6J5O6LiQt5LsBZDSi4qyVUdSLeYDnTtirw==",
    "email": "uberdevelopers@gmail.com",
    "mobile_verified": true,
    "promo_code": "uberd340ue"
}

Conclusion