Inline Referencing and GatewayScript Referencing of Parameters/Variables

Techniques for accessing Parameters using Inline Referencing and Context variables are slightly different. Path, query, and header type Parameters can all be accessed using request.parameters.[parameter-name] using the Inline referencing technique. But to access Parameters in the GatewayScript Policy, you will need to use request.headers.[header-name] to access the header type Parameters or request.parameters.[parameter-name] to access the query/path type Parameters.

6. Toggle the Show catches option. This will enable the Catches block. Click inside the Catches box to enable the Properties panel. Click Add catch.

You can build error-specific execution paths or a single execution path to handle multiple errors. Notice that the UnsupportedEnvironment exception that you recently created is in the list of errors to catch. This is shown in Figure 4.47:

Figure 4.47 – Throws you create are listed in available Catches

7. Select UnsupportedEnvironment and ValidateError errors in Catch 0. You will be handling both these errors under a common Catch flow.

8. Drag and drop a GatewayScript Policy on the Catch 0 execution path and name it Create Error Response. Copy the following code from GitHub, named errormsg.js, into this policy:

var errorName = context.get(‘error.name’);

var errorMessage = context.get(‘error.message’);

var errorResponse =

{

“name”: errorName,

“message”: errorMessage

};

context.message.header.set(‘Content-Type’,

“application/json”);

context.message.body.write(errorResponse);

The code demonstrates the method of accessing the error context variable in a GatewayScript policy. During the execution time, when an error is encountered, the error.name and error.message variables contain the name and the message of the thrown error. The other critical element to notice is the use of the message.header.set and message.body.write methods to set the Content-Type header and actual response, respectively. You can use the message.body.write method to create a message body for an invoke policy’s request as well. Use of the message.body.write method is not limited to generating custom API responses.

Your screen should look like Figure 4.48:

Figure 4.48 – Configuration of custom catch

9. The final step is testing. As you have done in the past, click Save to save your API. Now click on the Test tab to test your new error features.

ValidateError testing: Add an Environment header and assign it a value, Test. Put in a random patient-id that is less than 36 characters and see how the API behaves. You should see the error message you configured in your error routine pidcheck.js.

Figure 4.49 – Incorrect patient-id

The error message will be presented as follows:

{“name”:”ValidateError”,”message”:”Incorrect patient-id”}

UnsupportedEnvironment testing: In your test case, substitute the value of the Environment header for Production. You will remember that in the Production branch of your API proxy, you used a Throw policy to throw the UnsupportedEnvironment exception. Click Send to send the request. What do you observe? You should see an error message like the following:

{“name”:”UnsupportedEnvironment”,”message”:”Set

‘Environment’ header to ‘Test’ because ‘Production’

environment is currently unsupported.”}

The preceding section demonstrated ways to handle API Proxy error conditions. You can build upon these examples to handle different error conditions, both custom and APIC runtime specific.

You have now built a solid foundation of various APIC development features. Soon you will discover many other rich features of the APIC framework, starting with its support for modernization patterns, building RESTful services using FHIR (a healthcare standard), API security, GraphQL, advanced transformations, and much more. This chapter was just the beginning of a rich journey that lies ahead of you. This chapter got you to “buckle up.” Now is the time for you to “enjoy the ride.”

Summary

You started this chapter by installing and configuring a local development (Designer) and a testing environment (LTE). After getting a brief introduction to the OpenAPI Specification (OAS), you put your local environment to good use by developing a simple API Proxy. This simple proxy creation exercise should have helped you get your feet wet and prepare you for a long swim in the pool of APIC.

This chapter then took you into a deep dive into the extensive development framework features provided by the APIC platform. You were introduced to many Policy types (Built-in and Custom) and Logic constructs, with a particular focus on the Invoke policy. With the introduction to variables, you learned about various context variables (request and message, especially) available to you for the fetching and manipulation of data flowing through the API. API properties and their usage in an Invoke Policy taught you methods for building environment-specific dynamic target URLs.

As you worked through many step-by-step examples, you were introduced to the vast capabilities of the Invoke policy. You covered the capabilities of applying blacklists and the setup of error handling for timeouts. You even learned how to execute more than one call to multiple backend service providers as part of the same flow. You were also briefly introduced to GatewayScript (as part of numerous examples) and the switch policy. The switch policy introduction contained examples for building switch conditions using scripts and variables. These capabilities will be highly beneficial to you as you begin building more APIs with varying use cases. There was an extensive repository of hands-on examples that covered essential topics of error handling, customizing an API’s response, and advanced features of the Invoke Policy.

This chapter also explored multiple testing techniques available to you as a developer to test your APIs. Speaking of testing, you learned how to use the built-in test capability of APIC that includes the powerful feature of tracing. API Connect provides a one-stop shop experience by keeping development, testing, and tracing proxies in a single toolset – an ask of so many engineers!

You have seen just how quickly you can take an existing endpoint and create, promote, and test an API proxy. And with all the available features, Policies/Variables/Referencing, you as a developer can truly build robust, complex, and flexible APIs. But with great power comes great responsibility. The idea of API development is rooted in speed, agility, and simplicity. On your API development journey, if you observe yourself using all these features in developing a single API, it might be an opportunity to reflect on the design of that API itself. Food for thought!

With all this information and a solid base, you are now ready to take it up a notch and start with the modernization journey. The next chapter will teach you the techniques to expose hidden IT services to the outside world.