user1032531 user1032531 - 2 months ago 11
reST (reStructuredText) Question

What does it mean for a REST API to have a `required` response property?

Learning about REST APIs and am following https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-2-the-basics/.

The API can receive two parameters:

username
and
bla
, but only
username
is required by using the
required
keyword. This makes sense to me.

The API will return
firstname
,
lastname
, and
username
, but only
username
is required by using the
required
keyword. This does not make sense to me. Does the lack of the
required
keyword indicate that the other two might sometimes not be required? What influences whether they are or are not?

paths:
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username.
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
- name: bla
in: query
description: bla bla bla
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.

dwu dwu
Answer

Your interpretation is correct. If a property of a response object is listed in the required property list, is must be present in the response object for it to be valid, quite similar to the required field in a parameter object. Whether a non-required property is included in the response or not is up to the business logic of your application to decide.

Some more information with pointers to the relevant parts of the specification below:

  • The semantics of the required property list of a response object is defined as part of the Schema Object section of the OpenAPI specification. There it says that the schema object "is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it".

  • In the corresponding section on the required validation keyword of the JSON Schema Validation specification its semantics is defined as follows:

5.4.3. required

5.4.3.1. Valid values

The value of this keyword MUST be an array. This array MUST have at least one element. Elements of this array MUST be strings, and MUST be unique.

5.4.3.2. Conditions for successful validation

An object instance is valid against this keyword if its property set contains all elements in this keyword's array value.

  • You'll find further examples of how the required keyword can be used in the examples section of the JSON Schema specification or Part 5, Section 2.2 of the tutorial you're following.