How can you remove the Apigee proxy subpath from the proxy URL?

[amalik34]

Hi, I am looking to see if I can simplify the URL for our proxy by removing the proxy name sub-path.

By way of example, our proxy endpoint URL is www.example.com/{proxy-name-subpath}/api/endpointname where {proxy-name-subpath} is the name of both the proxy and the base path to the proxy.

We would like to simplify the URL by removing this proxy subpath, leaving the URL as simply www.example.com/api/endpointname, but I'm not sure if this is something that is possible on Apigee.

In searching for some documentation, I did see that there are some answers here for how to remove the proxy subpath from the target URL, but in this case I want to remove it from the external-facing proxy URL, not the target URL.

Is there a simple way to achieve this via Apigee?

Many thanks in advance for any guidance and thanks for reading my question.

[dchiesa1 · Accepted solution]

In Apigee, each API proxy has what we call a basepath. This is the left-most segment of the URL Path, the part that immediately follows the hostname. You can define lots of different API proxies, and each one that you deploy gets a unique basepath. This is how Apigee determines, for an inbound request, which API proxy should handle it.

The basepath can be a single path segment or a compound segment (with slashes contained within it).

You're asking, "can I simplify my API paths?". And the answer is "yes, but". Yes, you can simplify your paths, but if you use Apigee, you will always have a leftmost path segment as a distinguisher for your API Proxies.

if the structure of your URLs really is like www.example.com/basepath1/api/somethingelse , then... first I want to question why you need the path segment "api" in there? The guidance for RESTful APIs is to use a "collections and element" pairing. Let's suppose you run a restaurant and you want to expose a RESTful API that allows creation and management and query of reservations. A reasonable API path structure would be

# query available tables
GET www.restaurant.com/tables?query=xyz

# create a new reservation
POST www.restaurant.com/reservations
(response will return a reservation id) 

# view my existing reservation
GET www.restaurant.com/reservations/12763

# update/modify an existing reservation
POST www.restaurant.com/reservations/12763

# cancel an existing reservation
DELETE www.restaurant.com/reservations/12763

So in this case there are two "basepaths": tables and reservations. Both of these represent collections of objects.  The segment that follows the /reservations collection represents an individual element in the collection.  Eg /reservations/12763 represents a particular dinner reservation, and probably there is metadata associated to that reservation: a date, a time, a person's contact information, the size of the party attending, and any special instructions.    To implement this in Apigee, you can define a single API proxy with 2 proxy endpoints, covering both of those basepaths. Or, you can define 2 distinct API proxies, one for one basepath and one for the other. Either way supports this restful URL design in the same way - whether you use one proxy with two ProxyEndpoints,  or two proxies each with one ProxyEndpoint, will not be apparent to the external developer who uses the API. That's just an implementation detail.

Note, there is nothing like "api" in the URL path. It's obviously an API and that path segment is unnecessary. If you like you can include "api" in the hostname. For example, api.example.com/reservations . Also, your example included a final path segment of "/endpointname". I don't know what that denotes, but it doesn't seem like a very RESTful approach.  

To get more background on this topic, you might want to check out some older videos on URI design in API systems. Apigee did some videos a long time ago, but they are still relevant and helpful.

[amalik34]

Thank you so much for the thorough and prompt response. 

The examples I gave were more by way of example as opposed to how our actual URI paths are designed but nevertheless, the information and examples you shared were very helpful in thinking about how we can design our URIs with best practices in mind.

Much appreciated again, thank you!