To Proxy or Not to Proxy !includes - API Designer/Console/Notebook


When a RAML spec !includes other files, the parser, via a mediation layer, needs to go fetch those files. If they have an absolute URL, in a browser setting, the mediation layer can load directly from that URL, or can use a proxy service (hosted on the same domain as the current page) to load that file. Using a proxy has some pros and cons:

  1. Pro: The remote file can be hosted somewhere that doesn’t provide CORS, and still avoid the cross-domain restrictions that would otherwise break the loading
  2. Pro: If there’s a custom proxy service used, it can verify access, cache, etc.
  3. Con: A generic proxy service, if located outside the firewall, will not be able to access any resources within your firewall or on your desktop, greatly limiting the places you can host your !included files

Now, finer-grained controls can allow for all these cases, so e.g. the designer and console could have settings for whether to load from a proxy, from which proxy, etc. But since those settings are not attached to the RAML spec itself, how would you make sure those settings are also used when you publish your spec, load it from the notebook, etc?

Perhaps you could just use no proxy by default, but have a service into which you paste your URL and it returns the one of a proxy service for that URL, and then the author of the RAML spec can choose whether the URLs of the !included files in the spec are direct URLs or use the proxied URL?

Of course, you could also just use no proxy generally and ensure your !included files are only hosted on CORS-supporting servers.

Any thoughts on these or other approaches?


When I used the API designer my API went through 3 phases.

  1. “I have no place to put my !include resources”
  2. “I have a local server with my !include resources”
  3. “I have an externally accessible server for my !include resources”

I think case 1 is handled by local resource files within API Designer.
I like your suggestion for no proxy by default as it covers my use case for 2 and 3. Allowing a developer to choose to proxy is quite useful. For example, I’m creating the API but the group managing the application servers is different and trying to coordinate cross browser CORS support across groups involves a lot of back and forth.

Perhaps a more friendly approach to a style service (which requires the developer to go somewhere to take an action) is just to support a “proxy” URI scheme for the !include. So if a developer wants something proxied they would specific the include as

!include proxy:http://myserver:80/something/schema.json

I didn’t see in the RAML spec what URI schemes should be support for an !include.

Anyhow, I’m excited about these future changes.


Considering a proxy scheme is interesting. If we go with a type service, that could be plugged into the designer itself: you select a URL on an !include and click a button to turn it into a proxied URL. The end result isn’t as pretty, though it is more explicit as to who is proxying. That makes the spec portable, at least if the proxy service itself supports CORS.