Digital Transformation with IBM API Connect

An Invoke policy’s target URL is often built using variables and properties. Earlier, in the Create an API Proxy section, you created a proxy that utilized a static backend URL containing a hardcoded patient-id value (d75f81b6-66bc-4fc8-b2b4-0d193a1a92e0). You will now improve upon that proxy by removing the hardcoding of the patient-id value. Instead, you will now define patient-id as a parameter in your API’s definition and pass the patient-id value with the request message. You will then access this patient-id parameter using the Inline Referencing technique and dynamically build the backend service URL of the Invoke policy using the captured value of patient-id.

Before diving into the example, it is important for you to understand key Parameter types. Parameters represent the values that come as part of an API’s request. The following are the main types:

• Path type: Parameters defined at the path level are the variable parts of a URL path. These parameters cannot be omitted from the URL path. They are used to point to a specific resource. For example, a parameter defined as /customers/{customer-id} can be accessed as /customers/123 by an API consumer. In this case, API consumers will get details of the customer resource represented by customer-id=123. You learned about path-based Parameter usage in the example Accessing variables and properties in an Invoke Policy.
• Query type: Parameters defined as a query type are typically used to sort, filter, or paginate the resources. For example, a query parameter defined as /customers?firstName=Drew can apply a filter of firstName=Drew to the complete dataset before returning the subset data results to the API consumer.
• Header type: Header type Parameters can also be used to pass values to an API flow. You can use this type to pass custom values, such as security headers, to an API flow.

Now that you understand the key parameter types, it is time to create a new example of a REST API proxy:

1. On the Designer tool’s home screen, click the Develop APIs and products tile. Click Add | API.
2. Ensure that OpenAPI 2.0 is selected.
3. In the Select API type view, select From target service and click Next.
4. In the Info section, specify the following information:

Table 4.4 –API proxy details

5. Click Next. In the Secure section, unselect Secure using Client ID but keep CORS selected.
6. Click Next to create your API definition.
7. In the Summary section, click Edit API to further configure your API definition.
8. Go to your API’s Design tab | Paths section in the navigation pane. Change the default path (/) to /patient/{patient-id}.
9. Add a new path parameter by clicking on the plus icon next to Path Parameters (0). Create a new parameter with the name patient-id and assign it the values as per Figure 4.30.
10. Delete all the operations except GET. Click Save to save the definition.
    A completed screen is shown in Figure 4.30. It is important to understand all the things that are highlighted in this figure. There is a lot happening here. It is important to note that the parameters Located In path are always Required. Another thing to note is that the parameter defined in the path’s Name {patient-id} is inside curly braces and that it matches the value in the Name field.

Figure 4.30 – Path, Operation, and Path parameter creation

Now you need to set the target-url property to the backend endpoint.

11. Go to API Gateway tab | Gateway and portal settings | Properties. Click on the target-url property. Remove the value from the Property Value (optional) textbox.
12. Override this target-url property value by creating a catalog property in the sandbox catalog. Name this catalog property target-url and assign it a value of https://stu3.test.pyrohealth.net/fhir/Patient/. Click Save to save the definition.
13. With this setup done, let’s use the Inline referencing technique to construct the target URL for your Invoke policy. Go to the Gateway tab of your API and click on the only invoke policy on the canvas.
14. Remove the URL property $(target-url) of the Invoke policy and enter the following value:
    $(api.properties.target-
    url)/$(request.parameters.patient-id)
    NOTE
    You should understand the format of $(api.properties.target-url)/$(request.parameters.patient-id). This technique is called Inline referencing. You are using Inline referencing to access an API property (target-url) and a request Path parameter (patient-id) that you just define. You are also combining the two values to construct the final backend target URL.
15. Click Save to save your API. Enable the Online slider to publish your API.
16. Click on the Test tab.
17. You can now test the API proxy. Note the absence of the “X-IBM-Client-Id” and “X-IBM-Client-Secret” headers:

Figure 4.31 – Adding the value of patient-id

As you can see in Figure 4.31, the value of patient-id is required. Enter the value “d75f81b6-66bc-4fc8-b2b4-0d193a1a92e0” in the highlighted area. This value is the patient-id path parameter that you defined earlier.

18. Click the Send button and review the response.

Figure 4.32 – A successful test using Inline referencing

The preceding steps demonstrated the method of using inline referencing to dynamically build a target URL. As mentioned earlier, Inline Referencing coupled with API Properties is among one of the most used methods to dynamically build the target URL. Make sure that you develop a good understanding of this technique.