Note: This blog post is from 2020. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.

And what can you do about it, if you are on CF2016 or 11, and you want to use /api for your URLs? There are are two choices, depending on your needs: in brief, you can either:

• change your /api folder to a new name (which I realize may not appeal to all to some)
• or change the CF configuration, to STOP it treating /api specially for the API Manager's use. You would do this by editing two CF config files, urlworkermap.properties and web.xml (but this will break the ability of the API Manager to introspect REST services in CF2016 or CF11, though not CF2018)

TLDR; if you're bold and a risk taker, you can jump to the bottom to see my list of changes to make for that second option. As is often the case, there is risk in making changes in a cavalier fashion. There are various things to consider, and I warn of them below--but the good news is that this is a change that may take only minutes to do, once you've been careful to read about how to do it effectively.

Read on for more, including pros and cons of each choice, what to change and where, why this problem NO LONGER happens from CF2018 onward, and more.

(And if you are not familiar with the CF Enterprise API Manager, which is installed separately from CF, you can read about it here.)

What happened starting in 2016 (for ColdFusion 2016 and ColdFusion 11), and why?

Briefly, the problem is related to the CF API Manager (a feature that came out with CF2016), where Adobe added a mechanism to allow it (the API Manager) to introspect CF for any exposed REST services that the API Manager could be allowed to manage.

They did it by adding a newly defined /api URL that the tool would call. And this is NOT defined as some folder in your sites (or CF's wwwroot). Instead, it's defined as a servlet filter (and also handled specially by the CF web server connector, for IIS or Apache).

The effect on those already using /api for URLs

The problem is that many people already had their own apps that already used "/api", whether as a folder off the root of their web site, or perhaps written via some front-controller mechanism such as perhaps for their own REST implementation. (To be clear, the CF REST feature instead uses /rest for the URL by default.)

And even though the CF API Manager tool is available only for those using CF Enterprise, it's important to note that the problem could happen to you whether you were using CF Standard OR Enterprise (or the Trial or Developer editions), because the API Manager IS able to introspect even CF Standard instances if you ask it to, and so Adobe implemented a configuration change in all CF installations starting with with CF2016 (when the API Manager came out).

And how did it potentially end up impacting CF11 as well? Because Adobe added support for this same /api URL (and API Manager introspection) in CF11 update 11, which came out in December 2016. So if you were running on CF11 BEFORE that update and then applied that update, you would have hit the problem (if you use /api in your URLs). BTW, there's no mention of this in the CF11 Update 11 technote, but I found it through research and experimentation. I'm open to any needed corrections.

(This /api problem also briefly affected users of CF11 update 1, when in 2014 Adobe briefly added the /api path for a DIFFERENT reason, to serve as an alternative to the REST services use of /rest. This is mentioned in a 2014 bug report, though there is no mention of it in the technote for that update. Anyway, I have a machine still running CF11 update 6, and it does NOT show the two affected config files having a /api mapping, so I can only suppose that they realized the error back then and reverted that. If only they'd realized that same lesson in adding this support for the API Manager in 2016.)

Fixing the problem, choice 1: rename your /api folders to something else, if you're ok with that

The first choice does not require any change to CF, itself. You may simply accept the fact that in CF2016 (and 11), the /api path should regarded as a reserved word, and so you're ok changing your folder (in the root of your web site called /api) to some other name. That will certainly "fix the problem", for you and your app.

Others may prefer to "fix CF".

(Also, if you are tempted to stop here, just note that this "fix" may not be enough to prevent all problems that could happen on your server, about called into it for URLs with /api problem. As I discuss below, the fact that this tweak by Adobe involved the web server connector file, uriworkermap.properties, there is a chance that this could affect requests made to your web server that are NOT supposed to be going to CF. Again, see the next section for the fix to stop CF handling /api in a special way at all.)

Fixing the problem, choice 2: change the CF configuration to allow use of /api

Again, if you need to "stop CF from "interfering" with your use the /api in your requests (and you don't care to or need to use the CF API Manager to introspect CF REST services), then there are two files in CF which are configured (in CF2016 and CF11 after its update 11) to cause CF to watch for URLs with that in their path, and you could change both:

• the wwwroot/WEB-INF/web.xml file (under your CF cfusion or other instances)
• the uriworkermap.properties (under your CF config/wsconfig folder, in any numbered folders)

I'll show below WHAT to change, as well as share some things to watch out for, in the next two subsections.

Then you'd restart CF (to pick up changes to the first file) and your web server (for changes to the second file), and you'd be able to now use /api, without CF "tripping over it". (If you're curious about any negative impact to this change, read on to the sections that follow.)

About changing the web.xml file(s)

CF has long had a file called web.xml, which contains many XML elements, defining various "servlet mappings" that are vital to CF processing.

We must be VERY CAREFUL in editing this file. Indeed, you should save a copy of it before changing it, and be prepared to revert to the change if CF doesn't start or doesn't function properly after you "tweak it". (You could leave it in the same folder.) And since it's an XML file, you should also be very careful about how you edit it. Leaving or removing any character beyond what is proposed here could also make it not function (when CF loads it).

Where to find the web.xml file(s) to edit

As for where to find this web.xml file to change, you may noticed first that I have said "the web.xml file(s)". That's because for most people, you will indeed have just one web.xml file, the one in the /cfusion/wwwroot/WEB-INF/ folder under your CF2016 (or CF11) folder.

But note that if you may have implemented "multiple instances" of CF (which can be done in CF Enterprise, or Trial, or Developer editions), then EACH instance will have its OWN wwwroot, with its own WEB-INF folder and its own web.xml file. You will want to make the needed change in WHATEVER CF instance(s) you want to turn off this /api support.

(And FWIW, I am not discussing here how to change this in deployments of CF via a WAR or EAR file, as implemented on some JEE/servlet engine. I will leave those using such to figure out where this file with CF-based servlet mappings would be found.)

Now let's move on to WHAT to change.

What to change in the web.xml file

Again, the wwwroot/WEB-INF/web.xml file has various CF engine configuration elements, mostly in the form of "servlet mappings", and for this /api matter you will see that it has an element that looks like this:

That line is telling the CF engine to process any call to any url (that reaches CF) which starts with a pattern of /api/, and to hand that to the CFRestServlet. (And it's in that CFRestServlet that Adobe implemented the REST-based mechanisms which the API Manager was wanting to introspect.) Note also that such servlet mappings like this (which look like a folder name) don't really expect (or allow for) one to really HAVE a folder in their app of that name, like in this case /api. Again it's a "mapping", like a "virtual directory".

Anyway, assuming this set of XML elements is not already commented out (if it was, you'd not be getting the problem), you would want to comment out this set of lines (but again, don't forget to save a copy of the file before you start editing it.) You can comment out these lines by surrounding it with xml comments, as in:

(Note first that that is only TWO dashes on each comment line, not three as CFML supports. An XML file will FAIL TO BE PROCESSED if you use CFML comments in it. And second, no, we should not comment out the other XML elements in that file which would hold the CFRestServlet which this points to. That is used for other purposes besides this one.)

Remember also that you should modify this for the cfusion folder and any other CF instances you may have (if running Enterprise, Trial, or Developer and have implemented multiple instances.)

Finally, you should restart CF once you make this change (and restart each instance if you have multiple instances), for this change to take effect. Do be sure to check your CF instance by loading the CF Admin or your app, to make sure all is well. If not, revert to the backup you made above.

About changing the uriworkermap.properties file(s)

Recall I said there were TWO kinds of CF config files that needed to be changed. The other file that Adobe changed (in CF2016 and CF11) to support this API Manager call into CF was the uriworkermap.properties file. This is one of the set of a few file that exist to support the CF web server connector, which is the mechanism that allows requests to get from a web server like IIS or Apache into CF.

And like the web.xml, there are both potentially multiple copies of that file (in a given CF installation), for a different reason. And also again we should be careful about changing it, because if we make a mistake, it could break processing of requests into CF via that web server. So again, do make a copy of the file before editing it.

Where to find the uriworkermap.properties file(s) to edit

As for where to find this web.xml file to change, you may noticed again that I have said "the uriworkermap.properties file(s)", and that's because you may well have more than one. There is one created in each "web connector" folder that CF has created. The web connector folder is created either during installation (prior to CF2018) or using the CF Web Server Configuration tool.

And you may have only one "connector" (for all sites or some one site), or there may be more than one connector (for all or different sites), and then there will be at least one connector for each different CF instance (see above) or CF cluster (a feature of CF Enterprise/Trial/Developer), if you connect your web server to those.

As for where to find this "connector folder", regardless of whether you are running CF on Windows, Linux, or MacOS, and regardless of whether you are connecting CF to IIS or Apache, you will find in your CF installation folder a config/wsconfig folder, such as coldfusion2016/config/wsconfig. And in that folder you will find one numbered folder (like "1" or "2" and so on) for each web server "connector" that has been created for that CF installation.

And in each such numbered folder, you will find this file called uriworkermap.properties. Before we proceed, make a copy of that file, for safe-keeping. (You could leave it in the same folder.)

Now let's move on to WHAT to change.

What to change in the uriworkermap.properties file

The file only has only a couple dozen lines in it, all of which tell the CF web server connector whether and how CF would process requests whose pattern matches the patterns provided on each line. One of them (in the affected CF versions) will be this:

(If you don't see the line, see the next subsection here.)

That line tells the web server connector to let requests starting with /api/ (which make it to the web server connector) to be passed into CF for processing (which is then handled by that web.xml file above).

Again we would want to comment this line out, to stop the CF web server connector from handling the /api URL, as in:

Remember also that you should modify this for EACH numbered folder you find under CF's config/wsconfig folder.

Finally, you should restart your web server once you make this change/these changes (no need to restart CF for these connector changes). Then check that your app (using the web server and CF) does work. If not, revert to the backup you made above.

As for these changes to make to both files (and which to consider), I will offer a summary below of the steps to consider, if you are feeling a bit overwhelmed. :-)

Some special considerations about the uriworkermap.properties file, and connector updates

Before we leave the subject of updating this connector file, there are a couple of special considerations worth discussing.

(The connector files and folder are something that mystify many, but if you work with them every day like I do (helping people solve CF server problems, you get familiar with them and with the kinds of odd situations people can end up in. I have long planned to do a post on fixing/cleaning up/tuning the connectors...one of these days. I do have a recent one on updating them: When and how to upgrade CF web server connector, easier since CF2016.)

As for changing this uriworkermap.properties file, there are two ways that connector "updates" can bite you, regarding this /api matter.

1. First, note that if you create any new web server connectors, the web server config tool will implement the default lines for that file, and you will need to repeat this process for such a new connector to comment it out.
2. Along the same lines, note that if you remove and add back any connectors, the web server config tool again will reset all the connector files back to their defaults--and it will put that /api line back in (on CF2016 and CF11, after its update 11). Again, you will need to repeat this process to comment it out. (If you just use the "upgrade" feature, provided in CF2016 and above, that typically ONLY updates the connector file itself, the .dll file or IIS or the .so file for Apache. See my aforementioned blog post for more on that new "upgrade" feature.)
3. If you are indeed running on CF11 update 11 or greater, and you do find you do NOT see this /api line in the uriworkermap.properties file, then it is likely that the file you see was created by a previous version of the CF web server configuration tool (or the CF installer), before update 11 was put in place. Again, I discuss in the aforementioned blog post how it's important to update the web server connector after many if not most CF updates. But the point here is that if you don't see the /api line in a CF11 connector, it may mean that's an old connector. You will want to update it (see above), and then you will need to comment out that /api line.
4. Finally along the same lines, do beware that this problem of the /api url "breaking your app" may "pop up" "suddenly" in a CF11 implementation that has "worked for years", if someone does in fact run the web server configuration tool to create a connector after being on CF11 update 11 or higher. Again, you will want to comment out this /api line.

So who's affected if you DON'T make this change?

With all the technical details out of the way, and since it's been a lot to take in, I want to take a moment to help you recall just who needs to worry about all this.

First, the /api problem only going to affect those who a) are on CF2016 or CF 11 (with its update 11 or higher), and b) who have URLs whose paths start with /api.

And of course, if you did or will move from an earlier CF release to one of these affected ones, and you had a /api folder you used already, then you would have hit this problem right away. Or if you were or are doing new development on either of those two versions, and you create and try to use code in a /api folder, you would experience the problem. And some people probably saw this as a "last straw" and used it as motivation to "move off CF", which is a shame.

One last thought: it is also possible that this problem would/could affect even requests to existing NON-CF apps that use /api in their URLs, if those apps are served on a machine where one of the affected CF versions is installed, and the CF web server configuration tool has been used to configure the site serving that page. In that case, all requests are passed to the CF connector by default, and that connector looks at the uriworkermap.properties file to decide whether to "pass the request to CF" for processing. Again, that file has a /api mapping, in these affected versions. So changing that would help those folks as well.

Related to that, you may also find that the request DOES work if you make the API phrase capitalized or mixed case, but it won't work as /api (even if using a web server like IIS, .which should be case-insensitive.

Who's affected if you DO make this change?

Only folks who use the CF2016 Enterprise API Manager tool (a separate tool from CF itself, with its own installer, and which is ONLY available to those with a CF Enterprise license.) Again, this /api mapping in the effected files (web.xml and uriworkermap.properties) was only put into the CF config files by Adobe to serve the use of the CF API Manager to introspect CF REST services.

If no one in your organization uses the CF2016 API Manager, to introspect REST services in the affected CF instance, then there will be no negative impact of removing these.

Of course, if your org DOES use the CF2016 API Manager, then it will not be able to introspect the REST services in affected CF instances. (But this is NOT a problem in CF2018 or with the CF2018 API Manager.)

Who's NOT affected by this issue at all

First, the problem does NOT affect those running CF10 or below, since Adobe didn't modify it in 2016 like they did CF11 and 2016.

Second, it does NOT affect those running CF2018 and above, or using the CF2018 API Manager. Why is that?

Because Adobe realized the error of their ways, and fixed this by instead creating the CF configuration (in CF2018 and above) to instead handle the calls from the CF API Manager via a url called /cfapiresources. It's of course very unlikely that someone would already have a folder of that name, and it was ok for them to "stick cf in the font of it" because it was indeed used only for the API Manager's own use to call into a CF server it was pointed to.

That said, it is indeed a shame that the folks responsible didn't think of that in 2016!

And some may wonder why Adobe didn't then fix the problem in CF2016 (and CF11). In fact, they DID say in 2018 that they were going to do that (in a comment on the 2016 bug report filed about this whole /api URL issue). Sadly, that update to CF2016 and 11 never happened. I have confirmed that the problem remains in a CF2016 implementation with the latest update as of now, update 13. And this thus post.

Conclusion

Phew, another one of those long posts of mine. Sorry, but as I said at the outset, there are not only two choices of solution to the problem, but then plenty to consider about proceeding to the second choice (of changing the CF configuration). I have tried above to give you the info you need to do the job well. (Or of course, you can hire me to do it with or for you, in probably no more than 15 minutes.)

As I noted also at the outset, and repeated toward the end of the elaborated discussion of steps above, I am providing here a summary of the steps to take, if you DO want to proceed with the second option of changing the CF configuration (in CF2016 and CF11 after update 11) to get those CF versions to not regard "/api" as a special URL pattern (and you are ok to LOSE the ability of the CF API Manager tool to introspect your CF web services in those two CF versions).

• Find the WEB-INF folder(s), noting that there will be one for each CF instance you have (see above for more about CF "instances")
  • make a copy of the web.xml (for safe-keeping)
  • change it to comment out the lines related to the /api servlet mapping (being very careful about doing that)
  • do that for each CF instance you may have
  • restart CF (each CF instance you may have)
• Find the numbered folders under the cf config/wsconfig directory. there will be one for each CF web server connector you have (see above for more about "connectors")
  • make a copy of the uriworkermap.properties file
  • change it to comment out the one line referring to /api
  • do that for each "connector" folder you may have
  • restart your web server
• Beware that if you add new connectors, or remove and re-add current ones, you will need to repeat the process

Again, this whole matter was discussed in that 2016 bug report I mentioned above. And you will see I shared there in comments a good bit of what I have shared here.

And we could hope someone MIGHT find that bug report via google searching, but I still get people running into this /api issue in 2020, for people still running 2016 or 11 (including today, which sparked me writing this). I also tried to present the info in a more organized manner here.

Hope you found this helpful.

For more content like this from Charlie Arehart:

• Signup to get his blog posts by email:
• Follow his blog RSS feed
• View the rest of his blog posts
• View his blog posts on the Adobe CF portal

Need more help with problems?

• If you may prefer direct help, rather than digging around here/elsewhere or via comments, he can help via his online consulting services
• See that page for more on how he can help a) over the web, safely and securely, b) usually very quickly, c) teaching you along the way, and d) with satisfaction guaranteed