For several years CF has supported app developers using the CF API to map routes to specific ports on their application. This eliminates the limitations that apps must listen on 8080, and that they can only listen on one port. However, we weren't happy with the API design and it has been in a perpetual experimental state since we haven't been able to prioritize a redesign.
We've decided to declare stable support for the existing implementation in the v2 API, and do a redesign in v3. We've removed the experimental disclaimers for the 'ports' field on /v2/apps and the /v2/route_mapping resources. These changes will appear in the docs when the next capi-release is cut.
We'll get some documentation in place, but the workflow is:
1. Specify the ports your app will listen on with the 'ports' field of /v2/apps
2. Restart your app to recreate containers with the port opened
3. Use the 'app_port' field of /v2/route_mappings to associate a route with one of the ports the app listens on; it must be one of those configured in step 1.
My apologies this decision took as long as it did.
Product Manager, Cloud Foundry