Skip to main content
Version: ACE 5

API Routing Overview

NEW

This feature is available since version 24.5 and can be optionally enabled by setting ACE_API_SPLIT_ENABLED.

Managing API routes​

At some point it might become necessary to re-map a set of outdated APIs to a common base route or to disable a whole set of APIs. ACE make this possible by introducing the "routes" configuration.

What are "routes"?​

Routes are additional mappings on top of ACE APIs paths. Routes can be changed by editing the routes.yaml file (default) or any other file in routes folder from the ACE application. Using routes, it is possible to:

  • Map an API to a different base path
  • Map a folder of APIs to a common base path
  • Only allow an exclusive set of APIs
  • Resolve a conflict between two APIs that have defined the same path

The routes configuration can be accessed in the APIs page using the following button: Open routes configuration

Configuration​

This is the default routes configuration. The defaults make every API available at it's defined path.

Default configuration (no mapping)
routes:
  - apis: /
    # ^-- The filesystem name selector for which API(s) should be re-mapped.
    basePath: /
    # ^-- The base path to pre-pend to the selected API(s)

We could read the default configuration as "select every API and make it available from the base path". We can configure the apis property to select APIs by filesystem name, and the basePath property to map them to a different base path.

Explore various configurations in the samples section.

IMPORTANT: There are some minor caveats to using routes that need to be kept in mind:

  • Don't forget to include important APIs. An API must be matched by one of the apis selectors for it to be available. If you forget to include an API, it will not be available.
  • For folder matching add trailing slash (/) Apis selector matches API file path starting from /apis folder with startsWith() function. For example apis: /test will match /test-api/myApi.yaml as well, but apis: /test/ will match only files in /test folder (e.g. /test/myApi.yaml).
  • Order matters. If two routes select the same API, the route that comes last will override the previous one(s), so make sure to put more specific routes near the end.
  • All route files in routes folder are used. If there are multiple files in routes folder all file content will be merged and then used.
  • Multiple route files are merged Routes files are merged by order property (ascending) in routes file or as a fallback by their name alphabetically. This means that more important routes should be placed in a file that will be merged last.
note

If order property is not defined in routes file, it will default to 0.

Sample route configurations​

Here are some examples of how APIs can be routed.

Re-routing a single API to a different path​

See example
routes
  - apis: /
    basePath: /
  - apis: agent-get
    basePath: /deprecated

If there's an API in filesystem location /agent-get with path GET /agent, API will be accessible at GET /deprecated/agent.

Any additional APIs would be accessible from their exact paths as normal.

Re-routing a folder of APIs to a different path​

See example
routes:
  - apis: /
    basePath: /
  - apis: all-agents
    basePath: /deprecated-agents

If there's two APIs in

  • filesystem location /all-agents/agent-get with path GET /agent
  • filesystem location /all-agents/agent-post with path POST /update-agent

APIs will be accessible at

  • GET /deprecated-agents/agent
  • POST /deprecated-agents/update-agent

Any additional APIs that don't live in /all-agents folder would be accessible from their exact paths.

Exposing APIs from a specific folder​

See example
routes:
  - apis: all-agents
    basePath: /

If there's two APIs in

  • filesystem location /all-agents/agent-get with path GET /agent
  • filesystem location /current-time-get with path GET /current-time

Only one API will be accessible at

  • GET /agent
Why is only one API available in this scenario?

Because there is no route that matches the /current-time-get API file, it becomes excluded. Essentially, the routes configuration is acting like a whitelist for everything in the /all-agents filesystem folder.

Re-routing a folder of APIs to a different path except one API​

See example
routes:
  - apis: /
    basePath: /
  - apis: all-agents
    basePath: /deprecated-agents
  - apis: all-agents/agent-post
    basePath: /legacy-agents

If there's two APIs in

  • filesystem location /all-agents/agent-get with path GET /agent
  • filesystem location /all-agents/agent-post with path POST /update-agent

APIs will be accessible at

  • GET /deprecated-agents/agent
  • POST /legacy-agents/update-agent

Any additional APIs that don't live in /all-agents folder would be accessible from their exact paths.

Multiple selectors

Note that both the second and third route selects the all-agents/agent-post API. The route which comes last wins, which is why the POST /update-agent API is available at POST /legacy-agents/update-agent instead of POST /deprecated-agents/agent

Multiple route files​

See example

aRoutes.yaml

routes:
  - apis: /
    basePath: /

bRoutes.yaml

routes:
  - apis: agent-get
    basePath: /deprecated

In case above there are two route files, and both of them are loaded in alphabetical order by file name, resulting in the following configuration:

routes:
  - apis: /
    basePath: /
  - apis: agent-get
    basePath: /deprecated

Rest of the logic is the same as in the previous examples - APIs under agent-get will be available at /deprecated base path, but others will use / base path.

Multiple route files with order property​

See example

aRoutes.yaml

routes:
  - apis: /
    basePath: /
order: 1

bRoutes.yaml

routes:
  - apis: agent-get
    basePath: /deprecated
order: 2

In case above there are two route files, and both of them are loaded by order property, resulting in the following configuration:

routes:
  - apis: /
    basePath: /
  - apis: agent-get
    basePath: /deprecated

Rest of the logic is the same as in the previous examples - APIs under agent-get will be available at /deprecated base path, but others will use / base path.