How API Gateway Constructs URLs and Translates Them to Backend Calls

The URLs that your APIs have when hosted in API gateway and exposed to the world are different from the URLs of the backend services. Today we will explain how API gateway translates the calls that it gets into what it invokes and how each piece of that URL can be modified. We will be looking at a simple case of one-to-one translation when you just want to pass parameters and values to the backend as they are (you can modify them on the fly too - see some links at the end of the post):

1. API subscriber invokes something like apis.example.com/directory/1.0/users?identifier=123,
2. If apis.example.com is associated with your organization in API Cloud, the API gateway receives the call,
3. From the API context (directory) and version (1.0), the gateway identifies which API it should be calling,
4. The gateway "knows" the Production Endpoint for that API (or Sandbox Endpoint if that is what is being invoked),
5. It takes that endpoint and appends the resource, parameters, and values to it.
6. The gateway then passes that call to the backend.

Let's look at the elements of the API URL that the subscriber is invoking in the cloud:

• API gateway URL (in our example, apis.example.com) is the URL part that all your APIs will share. By default, API Cloud will assign you something like gateway.api.cloud.wso2.com:443/t/orgid/ - but you can easily change it to your own custom URL,
• Context is the URL path of that specific API (in our example, directory). All the REST resources of this API will share it (for example, directory/users directory/books, directory/groups). You specify that value on the first step of API design, right after the user-friendly name:

• Version is defined on that same step, right after the Context. If you do not want the version to be a part of your API URL at all, you can select the Make this the default version checkbox on the 3rd step of API editing:

• Resource is the HTTP noun that you use (users, books, groups, and so on). Just provide the name on the first (Design) step of API design in the URL Pattern box, select the HTTP methods you want to allow for this resource, and click the Add button:

• Path parameters (for example, /users/123) get added in curly brackets right within the URL Pattern box (for example, /users/{identifier}). Query parameters (for example, /users/?identifier=123) get added by expanding the API resource that you just added, typing the parameter name in the Parameters box, and clicking the Add Parameter button (see the picture below). You can then change the type of that parameter from query to header or formData.

• The values of the parameters will be provided by API users when invoking the APIs,
• Finally, we need to specify the backend base path for the API. On the second step of API design ("Implement"), select the Managed API option, and type the backend URL into the Production Endpoint edit box:

See also: If you want to also do some call transformations on the fly, here are a few additional posts on how to do that:

• Move query parameters to REST path
• Adding request headers to published APIs
• Multiple endpoints per API
• Convert a JSON Message to SOAP and SOAP to JSON
• Change the Default Mediation Flow of API Requests
• The Power of Mediators: API Call Transformation and Orchestration