Home » Using Optional and Nullable Properties in API Requests

Using Optional and Nullable Properties in API Requests

Using Optional and Nullable Properties in API Requests | APIMatic Blog

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 be focusing 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 down 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:

"paths": {
	"/products": {
  	"get": {
        ...
        "parameters": [
            {
                "name": "latitude",
                "in": "query",
                "description": "Latitude component of location.",
                "required": true,
                "style": "form",
                ...
            },
            {
                "name": "longitude",
                "in": "query",
                "description": "Longitude component of location.",
                "required": true,
                "style": "form",
                ...
            }
    	]
  	    }
      }
  }

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: trueproperty 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:

"Profile": {
	"title": "Profile",
	"required": [
  	"middle_name",
  	"rider-id"
	],
	"type": "object",
	"properties": {
        "first_name": {
            "type": "string",
            "description": "First name of the Uber user."
        },
        ...
        "promo_code": {
            "type": "string",
            "nullable": "true",
            "description": "Promo code of the Uber user."
        }
    }
}

For more detail, 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 object to JSON string and gets deserialized from 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:

Profile
{
   string picture;
   string first_name;
   string middle_name;
   string last_name;
   string uuid;
   string rider_id;
   string email;
   bool mobile_verified;
   string promo_code;
}

Its OpenAPI specification looks like this:

"Profile": {
	"title": "Profile",
	"required": ["middle_name", "rider-id"],
	"type": "object",
	"properties": {
  	"first_name": {
    	"type": "string",
    	"description": "First name of the Uber user."
  	},
  	"last_name": {
    	"type": "string",
    	"description": "Last name of the Uber user."
  	},
  	"middle_name": {
    	"type": "string",
    	"nullable": "true",
    	"description": "Last name of the Uber user."
  	},
  	"email": {
    	"type": "string",
    	"description": "Email address of the Uber user"
  	},
        "mobile_verified": {
    	"type": "boolean",
    	"description": "Mobile verification of Uber user"
  	},
  	"rider-id": {
    	"type": "string",
    	"description": "Rider id of the Uber user"
  	},
  	"picture": {
    	"type": "string",
    	"description": "Image URL of the Uber user."
  	},
  	"promo_code": {
    	"type": "string",
    	"nullable": "true",
    	"description": "Promo code of the Uber user."
  	}
    }
}

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

If promo_code is uninitialized during the Profile instantiation for the request, the resultant JSON will ignore promo_code, as it was an optional field.

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

If  promo_code is initialized with a proper value during the Profile instantiation for sending it in the request, the resultant JSON will include the field as specified:

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

2. Optional Non-Nullable

If a field (whether it’s a parameter or a part of the model) is uninitialized, i.e., not specified, then it should be ignored in JSON string during serialization but as it can not be initialized with a null value, hence we should ignore it 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",
     ...
}

If picture is initialized with a null value, it can be ignored in the resultant JSON as it is an optional attribute.

{
    "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",
   ...
}

If middle_name is initialized with a proper value, the resultant JSON will be:

{
    ...
    "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

It is entirely up to you how you incorporate the optional and nullable properties in your API calls. It is essential to handle null reference exceptions being thrown to the end-user, to avoid any unpleasant experience with your API. Learn more about what APIMatic offers for a comprehensive developer experience and how you can generate feature-packed SDKs with your API in just a few clicks. Stay tuned for more blogs that go into detail on how optional and nullable properties can be implemented in Java, C#, Python, Ruby, PHP, and TypeScript.

Leave a Reply

Your email address will not be published. Required fields are marked *