Proxy Mapping Rules
In this Article
- 1 Overview
- 2 View the List of Proxy Endpoint Mapping Rules
- 3 Create a Proxy Endpoint Mapping Rule
- 4 Edit a Proxy Endpoint Mapping Rule
- 5 Delete a Proxy Endpoint Mapping Rule
- 6 Prioritize the Proxy Endpoint Mapping Rules
- 7 Adding a Variable to the Proxy URL Path
- 8 Endpoint Mapping for URL Path Parameters in Specifications
Overview
A Proxy can have multiple endpoints; an endpoint can have multiple URLs. Depending on the conditions, you can create rules that choose which URL to redirect the request to using the APIM Expression Language.
A condition can be based on an expression, the existence of a key-value pair in the request header, the HTTP method, the URL path, or the existence of a key-value pair in the query parameters.
You can specify the authentication method and credentials to use at the target URL.
You can use the API Manager Expression Language in the path of your Proxy URLs to specify a variable.
View the List of Proxy Endpoint Mapping Rules
To view the list of a Proxy endpoint’s mapping rules:
In SnapLogic Manager, go to API Management > API Manager > APIs & Proxies.
Search for the proxy and click the proxy's name.
Go to the Proxy Endpoints tab.
Search for the endpoint and click the endpoint's name.
Go to the Mapping tab.
Create a Proxy Endpoint Mapping Rule
Go to the Mapping tab of the Proxy endpoint.
Click the add icon ( ).
In Create Proxy Mapping Rule, fill in the rule settings.
Rule Name. A name that is unique among the rules of the endpoint.
Target URL. The URL to which the request is redirected if the condition is met. This can be the URL to the third-party API that the Proxy refers to.
Condition. The condition that must be met for this rule to apply.
The condition can be:
Expression. The Target URL is used if the specified expression resolves to
true
.Header. The Target URL is used if the specified key-value pair appears in the header of the request.
HTTP Method. The Target URL is used if the HTTP method of the request is one of the specified values.
Path. The Target URL is used if the specified path matches the tail of the URL leading to the Proxy endpoint.
For example, if the Value is set toany/path/you/want
then the API consumer must send their request tohttps://elastic.snaplogic.com/myproxy/myendpoint/any/path/you/want
to trigger this rule.
The comparison is a case-sensitive exact match.Query Parameter. The Target URL is used if the specified key-value pair appears in the query string of the request.
Authentication. The authentication scheme required to use the API at the Target URL.
The authentication scheme can be:
Basic Auth. Enter the User Name and Password of the Basic Authentication account to access the API in the Target URL.
Key-Based. Enter the Key required to access the API in the Target URL and indicate where the Key is expected:
Custom Authorization Header. The request must include the key in the specified authorization header.
Custom Header. The request must include the key in the specified custom header.
Query Parameter. The request must include the key in the specified query parameter.
None. No authentication is required.
Click Create and Add Another or Create.
Edit a Proxy Endpoint Mapping Rule
Go to the Mapping tab of the Proxy endpoint.
Click the name of the rule to edit.
In Edit Proxy Mapping Rule, edit the rule settings.
See the descriptions of the settings in Proxy Endpoints.
Click Update.
Delete a Proxy Endpoint Mapping Rule
Go to the Mapping tab of the Proxy endpoint.
Select the rules to delete.
Click the delete icon ( ).
Prioritize the Proxy Endpoint Mapping Rules
Go to the Mapping tab of the Proxy endpoint.
Click the reorder icon.
In Reorder Mapping Rules, drag and drop the rules into the priority order that you want.
Click Save.
Adding a Variable to the Proxy URL Path
Navigate to the target Proxy and click the Mapping tab.
Click to open the Create Proxy Mapping Rule dialog.
Enter the appropriate information:
Enter a name for the Mapping Rule.
Click and in the Target URL Field, enter the URL with the variable. For example:
"https://www.maps.com" + request.uri.pathSegments[3] + ".driving-directions"
In the Condition field, select Expression.
Add the variable using the API Manager Expression Language. For example:
['page1','page2'].indexOf(request.uri.pathSegment[3] ) > -1
In the Authentication field, choose the appropriate authentication type for the Proxy.
Endpoint Mapping for URL Path Parameters in Specifications
Proxy endpoints are based on the segments in the 3rd party API URL. When the specification is uploaded, APIM interprets the elements in the API specification through the endpoint mappings. APIM automatically generates mappings for multiple paths with the same first path element.
For example:
The paths /pets
, /pets/{petId}
, /pets/images
generate an endpoint with the name /pets
and have mapping rules for each element as shown below:
/
/{petId}
/images
When you click on the Proxy, you can view the API endpoints from the specification in the Proxy Endpoints tab. These endpoints are based on the first path element of the endpoint, with all additional elements displayed as mappings.
Clicking the endpoint opens up the Proxy Endpoints Details tab, where you can view information about the supported HTTP methods for the endpoint.
In the Mapping tab, you can view the specific mappings as Rules and the Target URLs to call those API endpoints. The mappings are prioritized on the number of path elements and the number of dynamic path parameters.
The following examples describe how APIM handles three types of endpoint generation using the Swagger Petstore API specification.
Example 1 - Mapping and Expressions
When you click on the /createWithArray
mapping, the Edit Proxy Mapping Rule dialog opens.
The Target URL displays the full endpoint, and in the Expression field is a condition that determines when the mapping rule should be used.
Example 2 - Multiple Servers
The OAS 3.0 specification supports listing servers to different endpoints within an API. In Swagger Petstore Multi Server specification for the /pets
endpoint, the servers “http://petstore.swagger.io/vi/OVERRIDEPATH"
and “http://petstore.swagger.io/vi/OVERRIDEMETHOD"
are specified under "servers"
, as shown in the following image:
Since the Get and Post operation have different servers assigned to them, two mappings are created with the following syntax /<path>:[<list of operations for this server>]
. The following image shows these endpoint mappings:
The Edit Mapping Rule dialog for /:['GET']
includes an expression for the target URL where you can change the value:
From the API specification, you see that the server defined for the Get method (OVERRIDEMETHOD
) is a segment in the Target URL. Since the specification does not specify a server for the Post method but specifies the OVERRIDEPATH
as the server to the path endpoint, the POST endpoint uses that server in its Target URL.
Example 3 - Dynamic Endpoint
In the Swagger Petstore Dynamic endpoint specification, endpoints contain dynamic path elements {...}
as shown in the example below.
"paths"...
"/pets"...
"/pets/{petId}...
"/{userId}/pet/{petId}/purchase/foo"...
Some paths begin with dynamic parameters. For example, in the following endpoint:
/{userId}/pet/{petId}/purchase/foo
{userId}
is a dynamic field whose value can change
When the base path is a dynamic parameter, then the APIM generates an endpoint for each path:
/*
- the reserved endpoint that stores all paths whose first path element is dynamic/pets
- the base path and its supported URL paths
The Proxy endpoint /*
generated by APIM, contains the mapping rules for the various endpoints. You do not have to call the endpoint using /*
. Instead, call it based on the mapping rule.
The following image shows the rules and target URLs for the /*
Proxy endpoint:
For cases where the dynamic parameter exists in the path but not as the first element (such as /pet/{petId}
), it is appended to the respective endpoint (/pet
and /user
) as mapping rules.
Have feedback? Email documentation@snaplogic.com | Ask a question in the SnapLogic Community
© 2017-2024 SnapLogic, Inc.