General concerns

[gr0uch]

Hi, I'd like to address a few concerns about this package:

• The key names in the routes object seem redundant. This is mostly an aesthetic concern, but it does force the user to think of a name for a route, even if the route is self-descriptive.
• Not sure about the purpose of differentiating :, %, or * parameters, other than to have some sort of type casting. After all, the URL is just a string.
• Making the before method synchronous really limits what you can do with it. For example, what if I want to query the database to check if the currently authenticated user has permissions on a resource? Consider returning a promise or callback.
• Come to think of it, it might be missing an after method, which gets called after a resource is loaded, to transform the response.
• It's unclear how a route triggers an action. How does a route know what is the corresponding action?
• Is there any point to the helpers object, or is it there for organizational purposes?

P.S. I've authored a package that may be similar.

[josephwegner]

Hi Dali,

Before I respond to each of your points individually, I think there is a
misunderstanding about the relationship between routes and actions that
needs to be cleared up.

Route objects and action objects should be named the same - that is how the
action is chosen. Under the hood, Simple API loops through each of the
routes - the first things it checks is if there is an action defined with
the same name as the key of the route. Then it does the path matching and
parameter pulling, and passes all that to the matched action.

Now specific responses:

1. This was a very intentional decision. Other API frameworks (namely
   Rails) use simple action names (ie: PUT => update, POST=> create). Those
   work fine (not great) for top level actions, but nested actions are quite
   confusing. User-defined names make code much more readable, and do not
   require any future maintainers to understand Simple or common HTTP method
   patterns.
2. You're correct, those patterns are just for type casting. Admittedly,
   they add a significant layer of confusion, and I've considered removing
   them.
   I like them because you can define actions like getUserById and
   getUserByName with the same path, buy only the format of the identifier
   changes. I will consider if there is a better way to so this, or if I
   should just remove it completely.
3. I entirely agree. As I was upgrading all of my systems to v0.1 I kept
   thinking to myself "why the heck did you make this synchronous?!?!". This
   will be changed in the next major release.
4. I had considered an after hook, and then decided there was no need
   because of the convenience response functions. Simple does not do any
   fancy stuff after your controller actions are called, so any post
   processing you want done can be easily manually defined or just overridden
   in the response functions. That said, I'm not closed to the idea of an
   after hook - could you provide some use cases so that I can make sure I
   architect it in the most useful way?
5. This is explained in the leading paragraph. I would imagine your
   confusion comes from poorly written docs - I will update them to be more
   useful.
6. Helpers are purely for organization. The concept came from my PHP days
   with Zend. When learning Zend I often asked myself, "where is the right
   place to put this function?". Helpers were the solution there, and I think
   that's a great pattern. You can define helper functions anywhere - they
   don't need to be scoped into the controller - but I think having a defined
   place will keep controller formats consistent.

Also, Fortune looks great! Seems like a more poweful version of Deployd.

I have an eventual feature planned to write common top level controller
actions (PUT, POST, etc). That will require model integration, which is
something I'm thinking very hard about before I actually build it. I want
my models to be DB agnostic - I haven't found the right way to do that,
though.

By the way, I'm going to do a more formal review of these items and then
break them out into individual issues. That fits better with my ( and OS
in general) development processes. I'll copy you on each of the issues so
you get notified.

Thanks!
On Sep 10, 2013 1:05 AM, "Dali Zheng" notifications@github.com wrote:

Hi, I'd like to address a few concerns about this package:

• The key names in the routes object seem redundant. This is mostly an
  aesthetic concern, but it does force the user to think of a name for a
  route, even if the route is self-descriptive.
• Not sure about the purpose of differentiating :, %, or * parameters,
  other than to have some sort of type casting. After all, the URL is just a
  string.
• Making the before method synchronous really limits what you can do
  with it. For example, what if I want to query the database to check if the
  currently authenticated user has permissions on a resource? Consider
  returning a promise or callback.
• Come to think of it, it might be missing an after method, which gets
  called after a resource is loaded, to transform the response.
• It's unclear how a route triggers an action. How does a route know
  what is the corresponding action?
• Is there any point to the helpers object, or is it there for
  organizational purposes?

P.S. I've authored a package that may be similarhttps://github.com/daliwali/fortune.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/8
.

[gr0uch]

Ah, your explanation of the routes clears things up.

Just an example of how an after hook might be useful: setting the Content-Type on every response, without having to define this on each controller, or formatting the output in a certain way (no spaces for production, 2 space indent for dev).

I want my models to be DB agnostic - I haven't found the right way to do that, though.

This is something I've done with Fortune: define models once, use any adapter. Models are wrapped in a resource object, and the wrapper contains common methods to act on a model (find, create, update, delete).