RFC: Add sub resource support for REST controllers

[raymondfeng]

Description/Steps to reproduce

REST APIs sometimes represent hierarchical resources, for example:

• /customers/{customerId}/orders
• /customers/{customerId}/orders/{orderId}

For controllers, we can decorate methods to map to resource operations, for example

@api({basePath: '/customers', paths: {})
class CustomerController {
  @get('{id}')
  getCustomer(@param.path.string('id') id: string) {}
}

I'm proposing to support the following style so that we can have a chain of controllers to fulfill a hierarchical REST request.

@api({basePath: '/customers', paths: {})
class CustomerController {
  @locate('{customerId}/orders')
  locateOrder(@param.path.string('customerId') customerId: string) {
    let order: OrderController = ...; // Instantiated, injected, or located from the context
    return order; // Return an instance of OrderController
  }
}

When the router sees requests like GET /customers/{customerId}/orders or PATCH /customers/{customerId}/orders/{orderId}, it first checks if there are exact matches in controller methods that handle the verb and url. If no matches are found, the router will try to find a matching locate method (no http verb but with a path). In the example above, locateOrder method will be invoked and the returned controller instance will be used to further resolve/fulfill the rest of the URL such as GET / or PATCH /{id}.

class OrderController {
  customerId: string;

  @get('/')
   getOrders() { ...}

  @patch('/{id}')
  updateOrder() {...}
}

Prior arts

• https://docs.oracle.com/javaee/6/tutorial/doc/gknav.html
• https://dennis-xlc.gitbooks.io/restful-java-with-jax-rs-2-0-2rd-edition/en/part1/chapter4/subresource_locators.html

Additional information

[stale]

This issue has been marked stale because it has not seen activity within six months. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository. This issue will be closed within 30 days of being stale.

[stale]

This issue has been closed due to continued inactivity. Thank you for your understanding. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository.