Creating a parameter

Parameters define variable elements of a URL path, query parameters, headers, or a request body. You can create parameters for Paths and Path operations in your API definition.

Before you begin

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

About this task

Note: This task relates to configuring an OpenAPI 2.0 API definition. For details on how to configure an OpenAPI 3.0 API definition, see Editing an OpenAPI 3.0 API definition.

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.

At any time, you can switch directly to the underlying OpenAPI YAML source that corresponds to the design form in the user interface by clicking the Source icon OpenAPI Source icon. To return to the design form, click the Form icon Form icon.

Procedure

  1. Provide the following information:
    • Parameter Name: The name of the parameter.
    • Located In: 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 {}.
      • body: Parameters that describe the body of POST, PUT and PATCH requests.
    • Description: A description of the parameter.
    • Type: The data type of the parameter.
    • Format: Select the data format; the available options depend on the selected Type.
    • Select the following option as required:
      • Required: Determines whether this parameter is mandatory. If the Located In property is set to path, this option must be selected.
      • Allow Empty Value: Allows sending a parameter with an empty value. This is valid only if the Located In property is set to query.
  2. Click Create.
    The parameter details are displayed for further editing; see Editing a parameter.