-
Creating the API
<iframe width=”860″ height=”515″ src=”https://www.youtube.com/embed/StTNQPDYZCI” frameborder=”0″ allowfullscreen></iframe>
To skip all the instructions and just get the API: https://ibm.box.com/s/3oilh3rm4g1v3ivyhoh6geas5nqnpmo3
The follow section will walk an APIC developer through putting up public API which would echo back a desired response. This can be used as a static mock service to simulate a backend service response, and/or used to test connectivity between a client user and DataPower.
1. Log into the APIC designer (https://<your_APIC_server_url>/apim).
2. Click on the menu icon (the hamburger icon ) and navigate to the API section under Drafts:
3. Click on Add (+) > New API to add a new API.
4. Use the title myLoopbackAPI and remove the auto-filled Base Path /myloopbackapi to just the root slash /. Click on Create API.
5. Once in the Design section of the API, navigate to the Produces section to unselect the application/json content-type. This will allow you to use any content-type you desire later on.
6. Navigate to the Security section and uncheck the clientIdHeader (API Key) because we do not want to secure this API.
7. Navigate to the Path section and click on the Add icon (+) to add a path. Name it /myloopbackapi.
Note: This automatically generates a GET operation for this path. If other operations are desired, they may be added.
8. Click on the Save icon and navigate to the Assemble tab.
9. Inside the Assemble, hover over the Invoke policy and click on the trash can icon to remove the Invoke policy.
10. Drag and drop the GatewayScript policy to the main canvas.
11. Here you may specify the response you would like to see. For now, we have this api respond back with Hello. Therefore, you will enter the following into the gatewayscript policy:
session.output.write(‘Hello’);
apim.output(‘*/*’);
|
12. When the testing tool opens, ensure the Catalog you would like to use is chosen. For our case, Sandbox will be our catalog, and we will create a new Product called Test Product. Then click Create and publish.
-
Testing the API
To ensure the API is working, all you have to do is call the API.
https://<DataPower_Gateway_URL>/<Provider_Organization>/<Catalog>/myloopbackapi
You may also use the Test tool to test the API by just navigating through the next screen after creating and publishing the API from the previous section.
Note: The first time calling the API, you will get a security message from the browser stating that the self-signed SSL certificate is untrusted. Since this is a test API, there is no need to worry, accept the security warning, and continue.
After accepting the security, you will see your response.
Now, as you can imagine, you will be able to put anything in place of where the ‘Hello’ was input, to simulate a mock response for testing purposes. All you have to do is get a sample response, copy, and paste it into the gatewayscript policy created previously.
The response headers may be added to the mock response as well using the Set Variable policy.
-
Using this API as a mock service
In the scenario where you would like to simulate a backend service response, for cases where your APIC environment cannot get to the backend, you may use this API to simulate the response structure of the backend service body, and header for testing purposes. The requirement to achieve this is to be able to obtain the sample response of the real backend.
For the sample in this section, I will use a free API from the OpenWeatherMap organization to get my sample response: http://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b1b15e88fa797225412429c1c50c122a1
By going to the url on my browser, I get the sample as shown above and below.
Response Body:
{“coord”:{“lon”:-0.13,”lat”:51.51},”weather”:[{“id”:300,”main”:”Drizzle”,”description”:”light intensity drizzle”,”icon”:”09d”}],”base”:”stations”,”main”:{“temp”:280.32,”pressure”:1012,”humidity”:81,”temp_min”:279.15,”temp_max”:281.15},”visibility”:10000,”wind”:{“speed”:4.1,”deg”:80},”clouds”:{“all”:90},”dt”:1485789600,”sys”:{“type”:1,”id”:5091,”message”:0.0103,”country”:”GB”,”sunrise”:1485762037,”sunset”:1485794875},”id”:2643743,”name”:”London”,”cod”:200} |
Response Headers:
HTTP/1.1 304 Not Modified
Server: openresty/1.9.7.1
Date: Tue, 30 May 2017 21:03:04 GMT
Connection: keep-alive
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
ETag: W/”e70c27085ed41de5321252b16c9582fe”
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: adb6d0c2-2623-4db6-ab25-0a2238c77f4e
X-Runtime: 0.003190
|
13. Back in the Assemble section of the myLoopbackAPI, modify the gatewayscript policy à Replace the ‘Hello’ with the response body you would like to test. For this example, it would be the following:
session.output.write(‘{“coord”:{“lon”:-0.13,”lat”:51.51},”weather”:[{“id”:300,”main”:”Drizzle”,”description”:”light intensity drizzle”,”icon”:”09d”}],”base”:”stations”,”main”:{“temp”:280.32,”pressure”:1012,”humidity”:81,”temp_min”:279.15,”temp_max”:281.15},”visibility”:10000,”wind”:{“speed”:4.1,”deg”:80},”clouds”:{“all”:90},”dt”:1485789600,”sys”:{“type”:1,”id”:5091,”message”:0.0103,”country”:”GB”,”sunrise”:1485762037,”sunset”:1485794875},”id”:2643743,”name”:”London”,”cod”:200}’); |
14. Once completed, Save and Publish. Then invoke the API, and you will see your static mock response.
-
Adding HTTP Headers to an API
You can additional add or remove response headers from your API by using the Set-Variable policy.
For example, there appears to be an ETag response header from the original response header. There is no importance to the ETag header, it was just an arbitrary example used for this sample. By using the Set-Variable Policy in the APIC Assemble tab, you may add that header to your API.
15. Back in the Assemble of the myLoopbackAPI, drag and drop a set-variable policy before the gatewayscript policy.
16. In the set-variable policy, drop-down to use the Add action, enter message.headers.ETag in the Add section, ensure string is the Type, and the value matches the header from the original backend service call W/”e70c27085ed41de5321252b16c9582fe”.
17. After saving and re-publishing, you will see the header show up in your API.
-
High-Level Analysis of the transaction (Debugging)
In addition to using the Activity-Log policy for debugging purposes, a more indepth look into the transaction may be conducted on the syslogs and probe on the DataPower Gateway. You will not have access to the DataPower Gateway on Bluemix, therefore this section only applies to the on-prem environment.
The syslog and probe for the API calls will be found in the APIC generated domain on DataPower.
If you have multiple DataPower domains on a system, you may find the APIC generated ID from the CMC Services, listed in the DataPower Service section under DataPower Domain:
Debug Logs (syslogs)
WARNING: Debug logging may impact performance, therefore, it should be avoided in production.
- The syslog level is defaulted to warning level for APIC generated domains.
- The syslog file itself is titled default-log, and the name of rotated files are as follows: default-log.1, default-log.2, and default-log.3 (log rolls every 500KBs).
- The syslog is written to the logtemp directory of the File Management, therefore you may view the raw logs from the logtemp, or through a visual friendly parsed System Logs section of the DataPower WebUI:
- Setting the log level is in the Troubleshooting section of the webui. You will want to set this to Debug log level when debugging.
Most error transactions will not include the transaction ID, therefore, to narrow down the error, you must cross-reference the URI of the call, the time of when the error took place, and any other key indicators from the API.
The start of the transaction will acknowledge that DataPower recieved the transaction.
The syslog includes the datetime, the event ID, the service object type, the log level, protocol, transaction ID, client IP, and log message, as shown below. The example below is the last transaction from API created in this tutorial.
20170531T024253.740Z [0x80e0013a][mpgw][info] source-https(webapi-https): tid(36981154)[192.168.88.1]: Received HTTP/1.1 GET for /demo/sb/myloopbackapi from 192.168.88.1
Once the desired log details are found, the transaction ID may be cross-referenced for all the logs that belong to the particular transaction which you are debugging.
At debug level, the syslogs contain over 300 lines of debug details, therefore we wil not be looking at the full logs, although, to note that each log detail walks through each processing step throughout the APIC framework on the gateway, therefore, when an error is thrown, it is a good indicator of where to debug.
More about DataPower logs can be found in the knowledge center: https://www.ibm.com/support/knowledgecenter/SS9H2Y_6.0.0/com.ibm.dp.xm.doc/logtarget_logs.html
The Probe
WARNING: Probes may impact performance, therefore, it should be avoided in production.
- The Probe can be enabled in each gateway object, but the Troubleshooting section contains consolidated Probes you can enable/disable under the Debug Probe tab.
The probes will be rarely used for APIC work, unless there are deeper DataPower development work done such as building User-Defined Policies or Extensions.
More information about the Probe may be found in knowledge center: https://www.ibm.com/support/knowledgecenter/SS9H2Y_7.5.0/com.ibm.dp.doc/probe.html
The probe would be used mostly when APIC developers would like to leverage DataPower variables which may not be exposed for APIC, to verify that the context variables are being set properly, verify headers, troubleshoot DataPower extension variables, and/or etc.
By expanding the one transaction line item in the probe shown in the figure above, you will see that there are several calls made to process the request and response. The developer can see each step of the call, action to action.
The figure in this section shows a sample of analyzing the request transaction in one spot of DataPower as it traverses through the gateway:
1. Expansion of the transaction to see all the processing rules
2. Selection of the rule right before the response
3. Selection of the final action taken of this particular rule
4. and view of DataPower context variables used and/or can be used in this request alone.
From the same screen as shown in the figure above, the APIC developer will be able to scroll down to find the “var://context/_apimgmt/readContext” variable to see what APIC context variables are being set (after clicking show node to open the page). All these variables are listed in the API Connect context variable knowledge center page.
The APIC developer may also see the headers and response body of the transaction.
The take-away from this section is, the APIC developer can set and get variables from the system memory and leverage them for custom code, view headers for the transaction, the body of the message, and/or analyze the request for any additional errors which the error logs may not output.
Most of the time, leveraging the syslogs are enough for debugging.