Tutorial: Implementing a simple assembly for a REST API

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

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.

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:

1. In a command window, change to the project folder that you created in the tutorial Tutorial: Creating an invoke REST API definition.
2. 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.
3. In the API Designer, click the APIs tab.
4. Click Add > New API..
5. Enter the following details in the specified fields:
   1. In the Title field, enter Loans.
   2. In the Base Path field, enter /loans.
   3. Ensure that the version is 1.0.0.
   
6. Click Create API.
7. In the Paths section, click the Add Path icon .
8. In the Path field, rename your Path as /quote.
9. Click your GET /quote operation to expand it.
10. In the Summary field, enter Loan quote.
11. In the Description field, enter Provides details of the cost of repayment of a loan.
12. For your GET /quote operation, create three parameters by clicking Add parameter > Add new parameter 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.
13. Click the Assemble tab and then click your invoke policy. The property sheet of the invoke policy opens.
14. In the Title field, enter Cost invoke and, in the Description field, enter Retrieve the monthly cost of a loan.
15. 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.
16. 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.
17. 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:

1. Click the Design tab.
2. In the Definitions section, click the Add Definition icon .
3. Click the new definition to expand it.
4. 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.
5. Click Add Property to add a second property to your definition.
6. 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

7. In the Paths section, expand your GET /quote operation.
8. For your GET /quote operation's 200 response, set the schema value to Quote_Output.
9. Click the Assemble tab.
10. 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.
11. 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.
12. Click your map policy. The property sheet for the policy opens.
13. Click the Edit inputs icon in the Input column.
14. 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.

    

15. Click Done.
16. Click the Edit outputs icon in the Output column.
17. 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.

    

18. Click Done.
19. Click the circle corresponding to your Monthly_cost input and then click the circle corresponding to your monthly_repayment output.
20. Click the circle corresponding to your Monthly_cost input and then click the circle corresponding to your total_cost output.
21. 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.

22. Click the circle corresponding to total_cost. The Configure mapping window opens.
23. 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.
24. Click OK.
25. 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:

1. Click All APIs and then click the Products tab.
2. Click your Banking Services Product.
3. In the APIs section, click the Add API icon .
4. Select Loans and then click Apply.
5. In the Plans section, select the Basic Plan, and ensure that the Loans API is selected.
6. Click the Save icon to save your changes.
7. Click Publish and then click the target that corresponds to the catalog, organization, and server that you want to use.
8. Ensure that Select specific products is selected, and then select your Banking Services Product.
9. 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:

1. In your web browser, visit your Developer Portal site.
2. Click Login.
3. 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.
4. Click Apps in the Developer Portal dashboard.
5. Click Create new App.
6. In the Title field, enter Loan quoter and then click Submit.
7. Click API Products in the navigation bar.
8. Click your Banking Services Product.
9. In the Plans section, click Subscribe for your Loans Plan.
10. Select your Loan quoter application and then click Subscribe.
11. Click your Banking Services Product.
12. In the navigation bar, click Loans and then click your GET /quote operation. The test tool is displayed.
13. 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.
14. Under Parameters, provide example rate, loan, and duration amounts for the test.
15. 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