Generate good API resource paths
When you create an API endpoint (sometimes referred to as an “API”) you have to specify a base path and hostnames as well as paths for individual API resources.
The API endpoint you create specifies a collection of resources and operations that can be protected. It should specify one or more hostnames, and as a best practice all resources in your API endpoint should start with a base path. For example, a base bath of "/basePath" and a resource defined as "/foo" would be found at "/basePath/foo".
It’s important to specify a base path, If you don’t, you could see the following negative results:
- Settings and security policies associated with an API configuration with an unspecified base path will apply to all requests which go to any associated hostnames.
- The settings in the API configuration, except for those related to CORS and GZIP compression, will override any corresponding policy settings you defined in Property Manager for those hostnames.
You should only leave a base path unspecified if you use the associated property only for traffic to this API.
By default API matching and the base path are not case-sensitive. If you enable the option to make it case-sensitive, the entire path including the base path is affected.
Path parameters
Path parameters are not path segment parameters. A path parameter is a placeholder in the path used to indicate an entire path segment that is a parameter to the resource routing. For example, /api/users/{userId} includes a path parameter named userId.
A path segment parameter is similar, but the value is expressed within a path segment. For example, /api/user;userId=12345.
To avoid conflicts with other web resources, each API resource path must be unique. When entering a base path, you can use curly brackets ({}) to define path parameters (for example, /basePath/{pathparam1}). If desired, you can also define multiple path parameters (for example, /basePath/{pathparam1},{pathparam2},{pathparam3}). All path parameters that you define this way automatically appear in the methods that you select for each resource.
Case sensitivity
By default new API matching is not case-sensitive. We recommend leaving this default setting. If you’re confident that your origin will only match the URIs in a case-sensitive way, you can enable the case-sensitive URLs and parameters option so that URLs are only matched with case-sensitivity. This applies to the base path and resource paths.
Wildcards
You can use parameters to capture entire segments of a path. Sometimes it can help to support wildcards which can more broadly match or capture parts of a path segment.
You can use two types of wildcards:
?always matches any one character.*matches zero or more characters through the end of the current path segment.
If the evasive URL matching option is enabled for your security policy, it will match any number of characters regardless of path segment boundaries.
For example,/foo_barwould match both/foobarand/foobazbar. With evasive URL matching enabled, it would also match/foo/barand/foo/baz/bar.
Wildcards and resource endings
You can use wildcards almost anywhere in your path. The behavior when you use them near the end extends directly from the behavior described earlier, but we describe it here to give you a better understanding of the impact. Your URI can have four possible endings:
| Suffix | Evasive URL matching disabled | Evasive URL matching enabled |
|---|---|---|
| No wildcard | No special treatment. Optional trailing slash is permitted. For example, /foo matches:/foo/foo/It doesn't match: /foo/bar | No special treatment. Optional trailing slash is permitted. For example, /foo matches:/foo/foo/It doesn't match: /foo/bar |
| Slash | Not a valid entry because a trailing / is always considered optional. See "No wildcard" above. | Not a valid entry. See, "No wildcard", above. |
| Asterisk | Zero or more additional characters allowed in the final path segment. For example, /foo* matches:/foo/foo//foobar/foobar/It doesn't match: /foo/bar/ | Zero or more additional characters allowed in the final path segment. Additional path segments are permitted. For example, /foo* matches:/foo/foo//foobar/foobar/It doesn't match: /foo/bar/ |
| Slash asterisk | The path can have one additional, optional path segment at the end. For example, /foo/* matches:/foo/foo//foo/bar/foo/bar/It doesn't match: /foo/bar/baz | The path can have zero or more additional path segments at the end. For example, /foo/* matches:/foo/foo//foo/bar//foo/bar//foo/bar/baz/foo2/bar2/baz2It doesn't match: /foobar |
Updated 3 days ago