Defining Paths for an API

A Path is a unit of a REST API that you can call. A Path comprises an HTTP verb and a URL path. By configuring the Path, you define how the API is exposed to your developers.

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.

The Path is appended to the server URL to form the full URL. For details on configuring servers, see Defining servers for an API.

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

Open the API for editing, as described in Editing an OpenAPI 3.0 API definition.
If there are already one or more Paths defined, expand Paths.
To create a new Path, click the add icon alongside Paths in the navigation pane. To edit an existing Path, click the Path in the navigation pane.
Provide the following information:
- Path: A relative path to an individual endpoint.
  The path is appended to the base path to construct the full URI to access the APIs. The path must start, but not end, with the / character. A parameter at the end of the path can contain a qualifier to match one or more path levels.
  
  If you specify just the name of the parameter, then one level of that path is matched. If you want to allow for multiple levels of the path, you can prefix the parameter with one of the following qualifiers:
  - * to indicate 0 or more occurrences
  - + to indicate 1 or more occurrences
  The + and * qualifiers can only be used at the end of the path.
  
  For example, the path:
```
/petstore/{type}/{*category}
```
  matches the following paths, where only one type value is matched, but all (0 or more) categories are matched:
```
/petstore/cats
/petstore/cats/supplies
/petstore/cats/supplies/health
/petstore/cats/supplies/health/medicines
/petstore/cats/supplies/health/medicines/a/b/c
```
- Ref (available when editing an existing Path): A reference to a Path that is defined elsewhere, either in this OpenAPI definition, or in an external file. A reference enables reuse of a set of operations already defined for a Path in this API, or in a file that is either a complete API definition or an OpenAPI fragment.
  The reference uses JSON pointer notation. For example, a reference to a Path called /mypath in this API would have the following format:
```
#/paths/~1mypath
```
  The ~1 characters are used to escape the / character, which is being used literally in the path name rather than as a special character.
  A reference to a path in an external file called path_fragments.yaml would have the following format:
```
file://path_fragments.yaml/paths/~1mypath
```
- Summary: An optional summary, intended to apply to all operations in this path.
- Description: An optional description, intended to apply to all operations in this path. You can use CommonMark syntax for rich text representation.
If you are creating a new Path, click Create.
The Path details are displayed for further editing as described in step 4.
Click Save when done.