Editing a parameter

Parameters define variable elements of a URL path, query parameters, headers, or a request body. You can edit parameters that have been previously created for Paths and Path operations in your API definition.

Before you begin

Open the details form for a parameter. For details of the areas in your API definition from where you can edit a parameter, see the following topics:

About this task

  • 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 parameter is similar to a header, 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 headers, see Creating a header.

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.


  1. Provide the following information:
    • Name: Available if you are editing a parameter component, this name defines a key that enables this parameter to be referenced from elsewhere in the API definition; the reference has the following format:
      To change the name, click Update, then click Save when done.
    • Parameter name (required): The name of the parameter.
    • Located In (required): The location of the parameter. Select one of the following options:
      • query: Parameters that are appended to the URL. For example, url_path?myparam=myvalue.
      • header: Custom headers that are expected as part of the request.
      • path: The parameter value is part of the operation's URL, enclosed in {}.
      • cookie: Used to pass a specific cookie value to the API.
    • Description: A description of the parameter. You can use CommonMark syntax for rich text representation.
    • Style: Describes how the parameter value will be serialized depending on the type of the parameter value. Select one of the following options:
      • matrix: Path-style parameters defined by RFC6570.
      • label: Label style parameters defined by RFC6570.
      • simple: Simple style parameters defined by RFC6570.
      • form: Form style parameters defined by RFC6570.
      • spaceDelimited: Space separated array values.
      • pipeDelimited: Pipe separated array values.
      • deepObject: Provides a simple way of rendering nested objects using form parameters.
    • Select the following options as required:
      • Required: Determines whether this parameter is mandatory. If the Located In property is set to path, this option must be selected.
      • Deprecated: Specifies that a parameter is deprecated and should be transitioned out of usage.
      • Allows Empty Value: Allows sending a parameter with an empty value. This is valid only if the Located In property is set to query.
      • Explode: When selected, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.
      • Allow Reserved: Determines whether the parameter value should allow reserved characters, as defined by RFC3986 (:/?#[]@!$&'()*+,;=) to be included without percent-encoding. This property applies only if the Located In property is set to query.
    • Schema:

      To define a schema for the parameter, click Create, then refer to Creating a schema.

      If the parameter already has a schema defined, click View to edit the schema.

      For full details on editing a schema, see Editing a schema.
      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.
    • Example Value: An example of a parameter value. Whatever you enter here is displayed as-is in the Developer Portal.
  2. Click Save when done.

What to do next

If required, use the breadcrumb trail to navigate to another location in the hierarchy of the object you are working on.