Defining Paths for a REST API

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

To define a Path, complete the following steps:

1. In the navigation pane, click Develop, then select the APIs tab.
2. Click the REST API definition that you want to work with.
3. Click Paths, then click Add.
4. In the Path name field, enter the name of the Path, using the format /path_name.

   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

   Note: The full API does not have to be unique across all Paths in your IBM® API Connect system. However, if it is not unique then you must specify that an application is required to identify itself with a client ID when it calls the operation; the client ID is used to uniquely determine which operation to call, according to which Plan the application is subscribed to.

   For information on specifying application identification requirements, see Creating an API key security definition.

5. To add one or more HTTP operations to your Path, complete the following steps:
   1. In the Operations section, click Add.
   2. Select the operations that you want to add.
      You can select from the following operations:

      GET

      Retrieves data from the server.

      PUT

      Updates data that is stored in the server.

      POST

      Sends data to the server for processing.

      DELETE

      Removes data from the server.

      PATCH

      Applies partial modifications to a path. Unlike the PUT method, the PATCH method applies an incremental change rather than replacing the entire operation.

      Note: If you want to use the PATCH operation, your API Connect gateway must be running DataPower® firmware Version 7.0.0 or later, otherwise the request is rejected by the gateway.

      HEAD

      Requests the same response as for a GET method call, but without the response body. This method is useful for retrieving information that is written in response headers, without having to transport the entire content.

      OPTIONS

      Retrieves the HTTP methods and other options that are supported by a web server or an operation, without implying a resource action or initiating an operation retrieval.

      Note: For each Path, you can have only one of each type of operation.
   3. Click Add to confirm the addition of the selected Paths.
6. Optional: Add any parameters that you want to include for the Path and all of its operations, by completing the following steps:
   1. In the Path Parameters section, click Add.
   2. In the NAME field, provide a name for your parameter.
      Note: The query parameters appId, client_id, client_secret, and appSecret are reserved and cannot be used.
   3. In the LOCATED IN field, select where the parameter is located when your path operations are called.
   4. Optional: From the TYPE drop-down list, select the type of data that the parameter is expected to have when the call is received by API Connect. If you have set LOCATED IN to body then you can select a JSON schema that you have defined for your API. For more information about creating JSON schemas, see Step 6 of Editing an API definition.
   5. Optional: In the DESCRIPTION field, provide a description of your parameter.
   6. Use the REQUIRED check box to specify whether the parameter is required for a call to be valid.
      Note: If you specify that a parameter is required, the required field for the parameter in the OpenAPI definition file is set to true, so that the requirement is documented for consumers of the API. The requirement is not enforced by the IBM API Connect Gateway

      However, the requirement is enforced by the Developer Portal test tool, because the purpose of these tools is to explore the correct operation of the API.

7. Click Save to save your changes.
8. Configure your operations. For more information, see Configuring an operation. You must provide at least one property or response for each operation, depending upon the operation type.