A
header defines information that can be sent in an API request or returned in an API response. You
can edit headers that have been previously created in various places in your API
definition.
Open the details form for a header. For details of the areas in your API definition from
where you can edit a header, see the following topics:
Note:
- This task relates to configuring an OpenAPI 3.0 API definition. For
details on how to configure an OpenAPI 2.0 API definition, see Editing an OpenAPI 2.0 API
definition.
- OpenAPI 3.0 APIs are supported only with the DataPower® API Gateway, not with the DataPower Gateway (v5 compatible).
- For details of current OpenAPI 3.0 support limitations, see OpenAPI 3.0 support in IBM®
API Connect.
You can complete this task either by using the API Designer UI application, or by using the
browser-based API
Manager UI.
A header is similar to a parameter, with the following differences:
- Parameters carry actual data and are available to end users, headers carry meta data associated
with a request or response and are hidden from end users.
- A parameter can have various locations, the location of a header is always set to
header.
- A parameter can have various format styles, the style of a header is always
simple.
For more information on parameters, see
Creating a
parameter.
At any time, you can switch directly to the underlying OpenAPI YAML
source by clicking the Source icon 
.
To return to the design form, click the Form icon 
.
-
Provide the following information:
- Header name: If you are editing a header component, this name defines a
key that enables this header to be referenced from elsewhere in the API definition; the reference
has the following format:
#/components/headers/Name
To
change the name, click Update, then click Save when
done.
- Description: A description of the header. You can use CommonMark syntax for rich
text representation.
- Required: Determines whether this header is mandatory.
- Deprecated: Specifies that this header is deprecated and should be
transitioned out of usage.
- Allow Empty Value: The header can be sent with an empty value.
- Explode: When selected, header values of type
array or
object generate separate headers for each value of the array or key-value pair of
the map.
- Allow Reserved: Determines whether the header value should allow reserved
characters, as defined by RFC3986 (
:/?#[]@!$&'()*+,;=) to be included without
percent-encoding.
- Schema:
To define a schema for the header, click
Create, then refer to Creating a schema component.
If the header already has a schema defined, click View to edit the
schema.
For full details on editing a schema, see
Editing a schema component.
Note: You cannot edit the schema if it references a schema component, the schema configuration is
inherited from the schema component; for details on configuring a schema component, see
Defining schema components. You can, however, edit the referenced schema component but any
changes will be reflected anywhere that the schema component is referenced.
- Content: A content definition describes the content of the header.
To
define a new content definition for the header, click Add, then refer to
Creating a content definition.
To edit an existing content definition,
click the content definition name, then refer to Editing a content definition.
- Click Save when done.
If required, use the breadcrumb trail to navigate to another
location in the hierarchy of the object you are working on.