Problem #

The primary problem has to do with AEP-compliant APIs that have a subpath prefix. An example is something like:

api.example.com/users/v1

Here the resource path starts after a constant prefix in the API.

The question is: should APIs with a path prefix like this be allowed? and if so, how should the clients and consumers handle this?

Should APIs with path prefixes be allowed? #

Even today, having a path prefix is a very common attribute in APIs. Therefore, I don’t see much of an option here but to allow these.

Examples include:

To exclude these APIs from compliance because their existence of a prefix would significantly hamper the adoption of the AEPs.

Therefore, I think the choice to include support for this is more of a practical choice than one taken for an ideal design.

Problems with a path prefix #

Introducing this pattern, however, comes with challenges. Enumerating the difficulties, those are:

A path prefix breaks the collection/resource pattern #

The main issue with a prefix comes with the ability to semantically interpret the meaning of a path. The resource model in the AEP specific includes a pattern of collection, resource id elements. For example, take a book in a bookshelf:

/bookshelves/living-room/books/pride-and-prejudice.

From here, it’s very easy to understand the following:

  • there are two collections of resources: bookshelves and books.
  • books are a subcollection under a bookshelf.
  • The bookshelf in question is living-room, while the book in question is pride-and-prejudice.

If we add a prefix, say, cloud/v1:

/cloud/v1/bookshelves/living-room/books/pride-and-prejudice

Now there is some ambiguity: is v1 a cloud? Although this is immediately obvious to a human, to a machine there is no longer a discrete algorithm to extract collections and elements.

Addressing the problems #

Although the above brings up more abstract problems, we need to look at how to resolve them discretely. Thinking through where there are practical challenges:

How to reference a resource #

For a resource reference, the path to the resource is used. Should this resource include the path prefix, or no?

    # with the prefix
    book: "/cloud/v1/bookshelves/living-room/books/pride-and-prejudice",
    # without
    book: "bookshelves/living-room/books/pride-and-prejudice",

For protobuf APIs in the AEPs, the path of the resource is used directly in operations such as Get / Update / Delete. Therefore, it does not need the prefix.

For REST JSON APIs, the reference will probably, at some point, be used to reconstruct the full path. For example, a backend may perform a GET on the HTTP path of the resource to retrieve information about it. However, resolving that resource reference would require some knowledge of the API domain to begin with, so it wouldn’t be a stretch to also intern the path.

The biggest issue is with full resource paths - examples where a resource references another resource in a different API. However, that too could also be solved by including the full path, including the api name, which in turn would also include the path prefix:

{api name}/{resource path}
{api.example.com/cloud/v1}/{bookshelves/living-room/books/pride-and-prejudice}

So there are cases well handled as well.

Conclusion #

To support subpaths in API, I propose the following:

  1. full resource paths to other APIs always include the api name: this enables clients to retrieve the resource without knowledge of where the API description of that separate API exists.
    1. alternatively, the API could describe the API name it expects via an annotation. This would allow a client to resolve that path.
  2. modify the API names description to clarify that it can include a sub-path.
    1. this also solves a separate problem, where an API may have resources tightly coupled to a separate path.