You create an assembly for a REST API that transforms inputs to the API, the outputs of
invoke and proxy policies, and creates a new output, in IBM® API
ConnectIBM API Connect for IBM Cloud Version 5.0.7 and
later.
Before you begin
The following diagram shows the sequential flow through the IBM API
ConnectIBM API Connect for IBM Cloud Developer toolkit tutorials for working with API definitions that call an existing endpoint. Before beginning a tutorial, ensure that you have completed the previous tutorials in the sequence. You can click a tutorial in the diagram to open the instructions for that tutorial.
You must also have set up a DataPower® Gateway. For more information
about setting up a DataPower Gateway
server, see Using physical DataPower appliances as Gateway Servers
or Using virtual DataPower appliances as Gateway Servers.
About this task
The operation that you created in the previous tutorial is a
simple invocation of an existing service. Although an invoked service might suffice, often you do
not have an existing REST API that exactly matches your requirements and you want to expose a new
REST API. This REST API can be a combination of existing services, which might also require some
transformation or manipulation of the response that the existing service or services return.In
the following example, BankA wants to expose an
operation that provides details on the overall cost of a loan based upon the details of the loan.
However, at present, the BankA API for loans only
calculates the cost per month of a loan. Therefore, the new API definition is to include an assembly
that combines the output of the existing API with other inputs to provide customers with more
information.
In this tutorial you will complete the following lessons:
Creating a Loans API and
invoking a service using context variables
In this section, you create a REST API definition containing a single operation and an assembly
that invokes an existing endpoint and uses query parameters when doing so.
To define the Loans REST API,
complete the following steps:
- In a command window, change to the project folder that you created in the tutorial Tutorial: Creating an invoke REST API definition.
- Change directories to your LoopBack® project and enter the following command:
apic edit
After a brief pause, the console displays this
message:
Express server listening on http://127.0.0.1:9000
API Designer opens in your web
browser, initially displaying the login page if you haven't logged in recently.
Note: The login
page prompts you to Sign in with IBM Cloud. Enter your IBM Cloud credentials, which authenticates you
on IBM Cloud and provides access to the
API Manager features such as Publish, Explore, and Analytics. You will continue to work in API
Designer locally to create APIs, models and data sources.
Note: If you need to run the editor
on a different port, use the following command:
PORT=port_number apic edit
set PORT=port_number && apic edit
where port_number is the port number to use.
- In the API Designer, click the APIs tab.
- Click ..
- Enter the following details in the specified fields:
- In the Title field, enter Loans.
- In the Base Path field, enter /loans.
- Ensure that the version is 1.0.0.
- Click Create API.
- In the Paths section, click the Add Path icon
.
- In the Path field, rename your Path as /quote.
- Click your GET /quote operation to expand it.
- In the Summary field, enter Loan quote.
- In the Description field, enter Provides details of the cost
of repayment of a loan.
- For your GET /quote operation, create three parameters by clicking three times. Configure your three parameters as per the following table:
Table 1. Loan API input parameters
Name |
Located in |
Description |
Required |
Type |
rate |
Query |
Interest rate |
Yes |
number-float |
loan |
Query |
Loan amount |
Yes |
number-float |
duration |
Query |
Loan duration in months |
Yes |
integer-int32 |
These parameters form the input of your API. All three parameters are required for
the existing API that is called, but the duration will also be used later to calculate the overall
cost of the loan.
- Click the Assemble tab and then click your invoke
policy. The property sheet of the invoke policy opens.
- In the Title field, enter Cost invoke and, in the
Description field, enter Retrieve the monthly cost of a
loan.
- In the URL field, enter the following
URL:
https://apim-services.mybluemix.net/banka/v1/loans/quote?apr=$(request.parameters.rate)&amount=$(request.parameters.loan)&term=$(request.parameters.duration)
The
URL includes references to context variables, indicated by
$(context_variable)
. In this case, the only context variable
used is request.parameters
, which indicates that the variable is located in the
query parameters of the API request. Later in this tutorial, other contexts will be used.
- In the Response object variable field, at the bottom of the
Cost invoke policy's property sheet, enter
loan_invoke. This specifies that, instead of the invoke policy's response
being placed into the
message
context of the assembly flow, it should be placed in a new
context. Unlike the message context, the new context must be referenced directly, and will not be
automatically altered by the next part of the assembly.
- Click the Save icon to save your changes.
Mapping and transforming variables to create a new output
In this section, you will use a map policy to map and transform variables from both your API
input and your invoke policy's output.
To configure the output of your Loans API, complete
the following steps:
- Click the Design tab.
- In the Definitions section, click the Add
Definition icon .
- Click the new definition to expand it.
- In the Name field, enter Quote_Output and, in the
Description field, enter The monthly repayment and overall cost of
the loan for which the quote is supplied.
- Click Add Property to add a second property to your definition.
- Configure your properties with the following information:
Table 2. Output definition properties
* (Required) |
Property Name |
Description |
Type |
Example |
No |
monthly_repayment |
The monthly repayment for the loan. |
float |
46.35 |
No |
total_cost |
The total cost of repaying the loan. |
float |
556.2 |
- In the Paths section, expand your GET /quote
operation.
- For your GET /quote operation's 200 response, set
the schema value to Quote_Output.
- Click the Assemble tab.
- Filter your policies to display DataPower Gateway policies. If the radio
button to do so is not displayed, click the Filter policies icon above the palette.
- In the palette, click the map policy and drag it across to where a
dashed, gray box is displayed on the canvas, to the right of your Cost invoke
policy.
- Click your map policy. The property sheet for the policy opens.
- Click the Edit inputs icon in the Input column.
- Add two inputs by clicking + input twice and then configure the inputs
according to the following table:
Table 3. Map input
properties
Context variable |
Name |
Content type |
Definition |
loan_invoke.body.monthly_payment |
Monthly_cost |
application/json |
float |
request.parameters.duration |
Duration |
none |
integer |
Here the map policy references the loan_invoke
context that is created by
the invoke policy. In addition, it references the request
context as the message
is
changed between the API call and the map policy.
- Click Done.
- Click the Edit outputs icon in the Output column.
- Add an output by clicking + output and then configure the output
according to the following table:
Table 4. Map output
property
Context variable |
Name |
Content type |
Definition |
message.body |
Quote_Output |
application/json |
#/definitions/Quote_Output |
Because the map policy is at the end of the assembly, the message
context
is set.
- Click Done.
- Click the circle corresponding to your Monthly_cost input and then click
the circle corresponding to your monthly_repayment output.
- Click the circle corresponding to your Monthly_cost input and then click
the circle corresponding to your total_cost output.
- Click the circle corresponding to your Duration input and then click the
circle corresponding to your total_cost output.
The wires that connect your inputs and outputs represent the relationships between
the two. Currently, the default settings apply, where monthly_repayment is a
direct mapping from Monthly_cost, and total_cost is,
incorrectly for this scenario, a summation of Monthly_cost and
Duration.
- Click the circle corresponding to total_cost. The
Configure
mapping
window opens.
- In the Value field, enter the following
code:
$(Duration)*$(Monthly_cost)
This code changes the mapping from a
summation to a multiplication of Monthly_cost and
Duration. No context is required to reference the two input variables,
although other variables could be referenced if a context was included.
- Click OK.
- Click the Save icon to save your changes.
Publish your API
Because the map policy is not supported by the Micro Gateway, you need to
publish your API to a DataPower Gateway
before you can test it.
To publish your API in a Product, complete the following steps:
- Click All APIs and then click the Products
tab.
- Click your Banking Services Product.
- In the APIs section, click the Add API icon .
- Select Loans and then click Apply.
- In the Plans section, select the Basic Plan, and
ensure that the Loans API is selected.
- Click the Save icon to save your changes.
- Click
Publish and then click the target that corresponds to the catalog,
organization, and server that you want to use.
- Ensure that Select specific products is selected, and then select your
Banking Services Product.
- Click Publish. Your Product is now available through your gateway server
and visible in both API Manager and the Developer Portal,
Testing your API in the Developer Portal
Use the test tool in the Developer Portal to
test your API.
To test your API through the Developer Portal,
complete the following steps:
- In your web browser, visit your Developer Portal
site.
- Click Login.
- Provide a user name and password for the non-administrator account that you created in the Using the Developer Portal tutorial and then click Log in.
- Click Apps in the Developer Portal
dashboard.
- Click Create new App.
- In the Title field, enter Loan quoter and then
click Submit.
- Click API Products in the navigation bar.
- Click your Banking Services Product.
- In the Plans section, click Subscribe for your
Loans Plan.
- Select your Loan quoter application and then click
Subscribe.
- Click your Banking Services Product.
- In the navigation bar, click Loans and then click your GET
/quote operation. The test tool is displayed.
- In the right pane of the test tool in the Try this operation section, under
Identification for the Client ID, select your
Loan quoter application.
- Under Parameters, provide example rate,
loan, and duration amounts for the test.
- Click Call operation. In the Response section, the
response of your API is displayed.
Note: If you receive no response, navigate to the URL that is
displayed at the beginning of the Try this operation section, in a new
browser tab. Accept the security certificate, and then call the operation again.
What to do next
Try testing the existing API by visiting:
https://apim-services.mybluemix.net/banka/v1/loans/quote?apr=2&amount=1000&term=12
and notice that only the monthly_payment field is returned.
What you did in this tutorial
In this tutorial you completed the following activities:
- Created an API definition that invokes an existing API using context variables.
- Configured a mapping and transformation between the output of an invoke policy and the output of
your API.
- Published your API.
- Tested your API in the Developer Portal.