Creating a header

A header defines information that can be sent in an API request or returned in an API response. You can create headers in various places in your API definition.

Before you begin

Launch the header creation window. For details of the areas in your API definition from where you can create a header, see the following topics:

About this task

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 OpenAPI Source icon . To return to the design form, click the Form icon Form icon .

Procedure

Create the header; you can either create a header from scratch, or you can reference a header that is defined in a header component.
- To create the header from scratch, provide the following information on the Definition tab:
  - Header name: If you are creating 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
```
  - 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.
- To reference a header that is defined in a header component, provide the following information on the Reference tab:.
  - Header name: If you are creating 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
```
  - Reference from: Select a reference to a header component.
Click Create.
The header details are displayed for further editing; see Editing a header.