atuttle / taffy

:candy: The REST Web Service framework for ColdFusion and Lucee

---

PROBLEM: Creating REST APIs with the native functionality in ColdFusion 10+ and Lucee is verbose, complex, and developer-hostile. Or maybe you're still on an older version of ColdFusion.

SOLUTION: A framework that focuses on Developer Experience and helps you "fall into a pit of success". You've come to the right place. Taffy is low friction, simple to get started, and compatible as far back as ColdFusion 8. CF8 was released in 2007! 😱

---

What makes Taffy's developer experience better?

• It's terse. How terse? A functional API can fit into a tweet. (BEFORE they doubled the max tweet length!)
• Smart and secure defaults, easily overridden with metadata in most cases.
• Easy to debug: Error messages are returned as JSON by default.
• Integrated dashboard gives you a direct view into how Taffy has parsed your code.
• Optionally integrates with your favorite IOC libraries like ColdSpring and DI/1, or use the baked-in IOC.

Currently Supported Versions

• Taffy 3.3.x+
• Taffy 2.2.x

If you file a bug or ask for support please indicate which version of Taffy you're using. If it's an older release, we usually ask you to upgrade. Officially, we promise to support the current and previous minor releases and the last minor release of the previous major release. To the best of our abilities Taffy follows the versioning guidelines defined in semver.

Supported versions get priority for bug fixes. No promises are made to fix bugs filed against unsupported versions. If your version is supported and your bug is reproducible and isolatable, we'll do everything within our power to address it.

If you're on an unsupported version, upgrade is not an option in your case, and you still have an isolatable and reproducible bug, contact me to discuss further options.

Documentation

Primary documentation is available at docs.taffy.io, with a few of the more detailed guides remaining in the wiki for now.

You can contribute to the documentation

Contributing documentation changes is as easy as submitting a pull request with modifications to the markdown files in the /docs folder.

Roadmap

Features and bug fixes are coordinated via the GitHub issues list.

Community

The most active place where Taffy users and contributors gather is in the #taffy channel of the CFML Slack. It's a great place to ask for help. We also have a mailing list, but it hasn't been used much since the CFML Slack came around.

Need serious help?

If your problem is too big or too private to ask for help in a chat room, I am available to hire for freelance work.

LICENSE

The MIT License (MIT)

Copyright (c) 2011 Adam Tuttle and Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

taffy's Issues

Add a hook into the onRequest method after all request details have been discovered

Where, for example, an API key could be checked.

running a test suite in railo

HI,

I have cloned taffy.
I have placed it under my railo webroot (3.3.1). I have added a mapping to resources folder.
I have added a test_suite.cfm in tests folder:

testSuite = createObject("component","mxunit.framework.TestSuite").TestSuite(); testSuite.addAll("tests.baseTest"); results = testSuite.run(); //Now print the results. Simple! writeOutput(results.getResultsOutput('html')); //See next section for other output formats

Issue is that taffy does not even reach this code. I just get a white screen.
No error is logged.

Andrea

Ability to pass data from onTaffyRequest to resources

Currently possible by using request scope/etc, but would be nice to have a way that doesn't break encapsulation.

So-far undocumented but known issue: taffy_uri metadata for resource cfc's not escaped before creating regex

Must contain only a-z, forward slash, 0-9, and curly-braces {}. Should either escape or document this behavior.

Periods in URIs don't work

For example, trying to use an email address as a value, in:

/api/index.cfm/email/[email protected]

Doesn't work -- I haven't tested to see exactly what happens, but I've received bug report emails about it. I suspect it either chops off the ".com" or throws an error because it can't find a mime type that matches "com".

Input JSON is not properly detected and deserialized into arguments

Reproduce by using this tool: http://dev.sencha.com/deploy/dev/examples/restful/restful.html

A JSON packet is sent containing a "DATA" element, but it is not detected and handled by Taffy.

POST method to upload file

Hi,
I want my client being able to upload file using http PUT method through REST request. Is api.cfc having this support? I can see getPutParameters method at line 272 always return string type which is not true when client add file contents into PUT request. Any advice would be appreciable.

Br,
alim

Support for custom headers in response

Implemented through genericRepresentation class (addHeaders, getHeaders)

example consumer is CF9-only; need to port back to CF7/8 syntax

Add a way to return a status code without returning a data object

Browsing to root of API throws 404 with built-in server - can't find dashboard

Hitting the root of an API is supposed to redirect you to the API Dashboard, but this fails when using the built-in Webserver in CF8 and CF9. The problem has to do with trailing slashes on the URL. Line 36 of API.cfc says:

<cflocation url="#local.basePath#?#application._taffy.settings.dashboardKey#" addtoken="false" />

Hitting the API in the test suite that results in a redirect to

/taffy/test?dashboard

which results in a 404. Inserting a slash before the query string delimiter makes it all work:

<cflocation url="#local.basePath#/?#application._taffy.settings.dashboardKey#" addtoken="false" />

This problem doesn't occur for me when I'm hitting the api through Apache - only when using the built in server. I discovered this while trying to run the unit tests.

Add setting to allow cross-domain resource sharing

The code:

configureTaffy(){
  enableCrossDomainAccess(true);
}

Should add the following header to every response:

<cfheader name="Access-Control-Allow-Origin" value="*" />

Remove some/all deprecated functionality

Evaluate on a case-by-case basis.

Implement global representation class override

Potential error when not supporting the OOB default mime type

Consider:

• Custom representation class used; but doesn't support JSON
• Developer does not set a different default mime type (leaving the OOB default of JSON)
• Consumer does not specify mime type, just accepting the default

Taffy will attempt to serialize as JSON, and throw an exception. This should be prevented somehow.

Ability to add custom headers in onTaffyRequest

Would be nice if you could easily add a header in onTaffyRequest (eg, current status of rate limiting)

Create 1.0 documentation

Return null values in Json

I can't return simple null value in my Json, it gets converted to ""

Feature Request: Sub folders in Resources

It would be nice to be able to organize resources into sub-folders. Basically all that would need to change is the loadBeansFromPath in the factory.cfc would just have to be updated slightly to look recursively through sub-folders. What are your thoughts on an enhancement like this?

Global custom header support

Just like per-request headers can be added, it would be nice if a set of headers could be defined that would be added to every response.

Taffy should return ALLOW header for every request (other than a 404/500)

Partial patch submitted by AJ Mercer

Possible incompatibility with CF8

User reports this error, when simply trying to run the "api" example on ACF8.

Element _TAFFY.SETTINGS.MIMEEXTENSIONS is undefined in APPLICATION.
The error occurred in \taffy\core\dashboard.cfm: line 41

Need an error failsafe

Syntax errors and other mega-fails (eg, db offline) tend to blow up in a non-readable fashion (html). Should catch these and display in a simpler format.

Representation classes (custom and otherwise) should notify framework of available mime types, instead of using configuration functions

maybe via metadata?

Coldspring integration borked

Not sure when or how, but the ColdSpring integration won't work. For some reason the code is using (non-existant) beanExists() method instead of containsBean().

/ht Brian Panulla

Add ALLOW header for the current resource to all requests

Partial patch submitted by AJ Mercer.

Add support for the HTTP HEAD verb

HTTP HEAD verb should be supported.

Test suite should refresh the test application before running tests

In part, because tests are frequently run after switching branches, so code from the wrong branch could be cached.

Finalize 1.1 documentation updates

CF Builder Doesn't Like ":" in attribute names

CF Builder 2.0 doesn't like the colon in the taffy attribute names. For example:

component extends="taffy.core.resource" taffy:uri="/product/{productID}" {
}

The taffy:uri part makes the rest of the file have errors in CF Builder 2.0 and it also disables all of the code assist, and syntax highlighting. Is there anyway that I can change it to taffy_uri or something like that?

ENH to tokens: user-specified regex

This should mitigate the original issue described in #35. By allowing the developer to specify their own token regex, they can indicate whether the period is an indicator of format or part of the input data.

Some examples are buggy under 1.1RC

Crash on OS X

Trying to run the latest examples on ColdFusion 9 / OS X 64bit results in a non-descriptive error:

500 can't load a null

This is coming from somewhere in core/api.cfc but I've been thus far unable to pinpoint it. I've tried to track it down by commenting out the various methods until the CFC runs, but nothing obvious has jumped out.

JSONUtil example doesn't work on CF8

Uses an implicit structure, which was not added to ACF until v9. Just needs to be changed to a declared struct.

Use bean factory to manage & resolve dependancies of representation classes

In addition to finding methods named "setX" and sending it bean id "X", it would be cool if the representation class (both default and per-request) could be a bean id that would be searched for in the bean factory.

Implement the "Accepts" header to tell the framework which mime type we want the data back as.

See: http://www.w3.org/Protocols/HTTP/HTRQ_Headers.html#z3

Error reading ColdSpring Factory and Abstract beans on configure

If your ColdSpring 1.2 configuration declares Abstract or Factory Bean types, Taffy will throw an exception when examining these objects to see if they are Resource classes. The direct cause is that ColdSpring doesn't (can't?) really expose the actual class that will result from these meta bean types (very Schödinger's-Cat).

Since Taffy can't really tell if the final class of these objects will be a Resource bean, it should probably skip them. If you really need to use a factory to generate your resources, you can tell Taffy which beans are Resources by supplying a beanList argument to setBeanFactory().

I already have a patch for this... I'll send a pull request.

Add headers argument to throwError() to allow adding custom headers

Railo handles relative paths differently than ACF

For example, in the basic /examples/api/ example, whereas ACF uses /examples/api/ as the base path for the relative lookup of "resources.beanName", Railo expects /taffy/core/resources/beanName.cfc.

This should be something resolvable by caching the location of Application.cfc on app startup; but it would be nice if we could update the framework + factory to try and make it work without mappings...

Refactor framework setup to not require use of applicationHook

Use custom function instead

problem with regex matching for uri's

/doco/component/tab
/tab

Both are matched by the generated regex. Need to add a ^ to the front to force it to match from the start. (Also need to verify this doesn't break anything...)

Thanks to Gary Menzel for the bug report!

Using an override representation class can cause errors

Because the default mime type is inspected at api startup and a custom representation class can be overridden on a per-resource basis (which doesn't necessarily have to implement the global default mime type), an exception would be thrown if the override representation class doesn't implement the default mime and none is specified.

Unknown formats specified in url (".xml") included in token values

Introduced with resolution to #32

Unknown formats (eg ".xml" in an API that only supports ".json") will be included in the token value. Not a great solution, but hopefully we can improve on it.

Get added to Railo extension installer thingy

http://blog.getrailo.com/post.cfm/railo-extension-store-has-opened

when request content-type is "application/json" CF seems to think the body is binary

Fix applied in our work framework:

<cfif IsBinary(requestBody)>
    <cfset requestBody = CreateObject("java","java.lang.String").init(requestBody,"UTF-8") />
</cfif> 

This assumes UTF-8; but the encoding should also be read from the request.

Add support for Railo

Will require testing & refactoring

cache resource cfc's on original instantiation

currently they are trashed after reading metadata; and then reinstantiated and cached on first actual use. could save time (at the cost of a little more memory) by caching after reading metadata.

missing local scope in duplicate URI error cfthrow message

In API.cfc line 414 was throwing errors for me (CF Builder 2 was having issues with renaming files, got two files instead, causing the error to fire). Here's the line:

<cfthrow
    message="Duplicate URI scheme detected. All URIs must be unique (excluding tokens)."
    detail="The URI for `#beanName#` conflicts with the existing URI definition of `#application._taffy.endpoints[metaInfo.uriRegex].beanName#`"
    errorcode="taffy.resources.DuplicateUriPattern"
/>

Fixed with:

<cfthrow
    message="Duplicate URI scheme detected. All URIs must be unique (excluding tokens)."
    detail="The URI for `#local.beanName#` conflicts with the existing URI definition of `#application._taffy.endpoints[local.metaInfo.uriRegex].beanName#`"
    errorcode="taffy.resources.DuplicateUriPattern"
/>

Revisit import of ColdSpring beans

See comments and notes in this commit:

https://github.com/bpanulla/Taffy/commit/a819e1a4d7c7b17b71b5893422ea0ad8a7167446

Is there another way to inspect beans coming from ColdSpring to determine if Taffy is interested in them?

Convert test suite to CFML Tags so it's useful on CF8, Railo, etc.