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. If you have not previously pinned the UI navigation pane then click the Navigate to icon .
   The API Designer UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon .
2. Click Drafts in the UI navigation pane, and then click APIs.
   The APIs tab opens.
3. Click APIs.
   The APIs tab opens.
4. Click the REST API definition that you want to work with.
5. In the Paths section, click the Add Path icon .
   A path is added.
6. In the Path field, add a path segment.
   Note: The full API, which is formed from the base path of the containing API followed by the path segment you define here, 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.

7. By default, the GET HTTP operation is used. To remove an operation, click the Delete Operation icon to its right.
8. To add another operation type, click Add Operation. Depending on what function you want the operation to provide, select one of the following HTTP 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 IBM 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..
9. Optional: Add any parameters that you want to include for the Path and all of its operations.
   1. Click Add Parameter in the Path section.
   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 found in the call of your operation.
   4. Optional: If you selected Path in the previous step, you must define the location of the parameter in the Path field in the following form:

      /Path_Segment_1/{Parameter}/Path_Segment_2

      where:

      • the Path_Segment variables are the names of your path segments.
      • Parameter is the name of your parameter. It must match the name used to define it in step 9.b
   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.
   7. Optional: From the drop-down list for Type, 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 24 of Composing a REST API.
10. 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.
11. Click the Save icon to save your changes.