I have been glancing at a RESTful specification available on http://restfulobjects.org (direct link to spec here). It is a little different from other things I have seen, but it makes sense, and having examples and clear specifications makes my development a lot simpler.
According to the standard, the URIs will be like:
api.example.com/object/user/31
api.example.com/object/user/31/properties/username
api.example.com/object/user/31/collections/channels
api.example.com/object/user/31/actions/someFunction
api.example.com/object/user/31/actions/someFunction/invoke
See this answer for a brief explanation of the structure. It is quite clear.
Note: This is not a discussion whether or not services/actions can be
represented as resources. There is a good discussion on that topic
here: http://www.infoq.com/articles/Intro_Restful_Objects. Look towards the end of the comments section.
My project is still on the drawing board, and most design elements up for grasp. I will however be using Symfony. I have my entities, and I have some services that act on those entities, and I have controllers to define what the services will do in a specific context.
And so to my actual questions:
...the Restful Objects spec is not based on the MVC pattern - it makes
no assumptions about the architecture of the server that implements
the API. In the URL:
~/objects/customers/31/actions/lastOrder/invoke
the 'actions/lastOrder' is not specifying a controller action, it is
specifying an action (i.e. a method) on a domain object (customers/31)
How do I structure my controllers in the most efficient way if I want to use the specification in an MVC application? Considering that the controllers would somehow serve different resources (objects, services, domain-types) as well as different representations of that resource. What are my layers?
Update Do I have e.g. a customer controller? An generic object controller? A useraction controller?
Do I need to rethink my whole entity/services approach? i.e. the solution for how to implement this is beyond the controller structure? (I fear it is, and then I do not know my next step)
For simplicity/efficiency I would like to make use of the FOSRestBundle and NelmioAPiDocBundle. I believe this can be done, but I then am concerned the spec will only serve as a url template for me, and not being implemented in my logic/design since I have to massage my framework to fit the URL somehow.
Please excuse my ignorance if this question has an obvious answer. I am new to RESTful APIs. If it comes down to a subjective perspective on implementation model, please give me some pointers, because I am currently at a loss for how to approach this.
From the "What is Symfony2 ?" article of Fabien Potencier:
Is Symfony2 an MVC framework?
If you look around, every single framework seems to implement the MVC pattern. And most of them are advertised as MVC frameworks... but not Symfony2. Have a look at the documentation, and you will see that the MVC pattern is only mentioned once or twice, but Symfony2 is never defined as being an MVC framework.
A bit later in this post:
Symfony2 is an HTTP framework; it is a Request/Response framework.
That's the big deal. The fundamental principles of Symfony2 are centered around the HTTP specification.
...
Sometimes, you just need a way to create a REST API. Sometimes, the logic is mostly in the browser and the server is just used to serve data (think backbone.js for instance). And for these projects, you don't need an MVC framework. You need something that handles a Request and returns a Response. You need a framework that implements the HTTP specification. HTTP streaming is yet another example that does not fit well with the MVC pattern.
...
And if you like to call Symfony2 an MVC framework, then you should know that Symfony2 is really about providing the tools for the Controller part, the View part, but not the Model part. It's up to you to create your model by hand or use any other tool, like an ORM.
As Symfony is a set of components, you can easily adapt your usage of the framework to the project you are working on, and the principles that you want to follow (here a REST specification).
The FOSRestBundle is very extensible.
You can define your routes manually, create different views of your objects through serialization.
Plus, I think you can keep very light controllers by writing the most of your objects management's logic inside Repository classes.
So,
Use simplified models and serialization to have different views/layers of your objects.
You should not rethink your whole Entity/Services in order to be more REST, just give them some changes/improvements in order to use them through data-transfer objects/domain objects (models) and Repository classes (fetching/storing methods).
You should be able to take benefits of use REST utilities such as FOSRestBundle, it provides more than built-in actions, allows you to make all custom stuff that you could need, be MVC or not, and be REST or not. It's at your own appreciation.
Have you considered using either Naked Objects (for the .NET platform) or Apache Isis (for the Java platform)? Both of these give you a complete Restful Objects compliant restful API for free - derived entirely from your entity models. (I am responsible for the first of these two. Our implementation is built on top of the ASP.NET WebApi framework. We have a RestfulObjectsController, with many methods on it, but these are all generic methods, corresponding to the various Restful Objects resource types - we do not need to add any new methods specific to the domain objects or their actions.
Related
Goal
I've been tasked with versioning a pretty large PHP Lithium API.
The end result I'm looking for is to use namespacing to separate the versions.
For example, normally a lithium route that looked like this:
Router::connect('/{:controller}/{:action}/{:id:\d+}');
Could have the following URL, map to the following PHP call:
http://www.fungames.com/game/view/2
app\controllers\Game::View($gameId)
But I would like to create the following mapping:
Router::connect('/{:version}/{:controller}/{:action}/{:id:\d+}');
Such that the following two calls could be made:
http://www.fungames.com/v1/game/view/2
app\controllers\v1\Game::View($gameId)
http://www.fungames.com/v2/game/view/2
app\controllers\v2\Game::View($gameId)
Problem
Unfortunately, the Lithium documentation doesn't make much mention of API versioning. There's a brief mention here as an example of continuation routes. But that approach would required making if statements in my controllers to version my API, and I personally consider that a poor approach.
TLDR
What is the best way to achieved namespaced API versioning when using the PHP Lithium Framework?
API versioning is a really broad topic, and while Li3 gives you all the necessary tools to implement any approach you choose, the actual implementation is up to you. Having said that, the routing layer is fairly sophisticated and will get you very, very far. See this gist on routing configuration examples.
Combining this with Request::get() which allows you to match on any request parameters including headers (you can pass get()-compatible values as $params in Router::connect() — see examples here),
and Request::detect(), which allows you to implement custom matching logic, you can send any configuration of values down to the controller/dispatch layer. This allows you to segment your versions by differently namespaced controllers (with fallback to the default), prefixed actions, or pass a namespace/class path for a different model.
Yet another approach, and one that I would recommend in the general case, is implementing a set of transaction managers/mappers for any endpoints that need to be versioned, and using them as an intermediary between your controller and your model, then use routing to switch between them.
This approach is made easier if you evolve your API using, i.e. content types, since you can choose a mapper based on that. This is also nice since version numbers are strongly discouraged by REST's creator.
Anyway, hope that helps.
The symfony 2 installer gives a best practice directory structure, but not a lot is said about how these directories should be used, where does each piece of code belong, sure the symfony framework narrows it down to views, entities and controllers, services etc. but more often then not, programmers end up putting a DQL query inside a controller and some logic to handle a specific task, while this does the job, there has to be a better method, even beyond symfony's out of the box directory structure, currently on a quest for better design pattern that would modularize and reuse as much as possible
On this quest, found a couple good articles on the interwebz, and spent a day on it, came up with a plan to separate all DB interactions to repositories, all logic to services, and keeping the controller 'thin' which acts as a central point for calling methods from repository and calling services. sounds good, will be modular and code can be reused.... BUT
This somehow moves away from OOP concepts and right into procedural programming, not that there is anything wrong with it, its just not leveraging the powerful concepts of OOP
Could making the objects more 'powerful' by adding in more functionality make it better? the services by definition should do a unit of task, will my approach make them big and ugly
a few good points on this blog here but could't really make out what they were trying to suggest as a solution
In general, the more behavior you find in the services, the more
likely you are to be robbing yourself of the benefits of a domain
model. If all your logic is in services, you've robbed yourself blind
-Martin Fowler
to summarize is Service oriented approach not leveraging the concepts of OOP? and how could this be supplemented
One of most important thoughts which you can find in Fowler's "Patterns of Enterprise Application Architecture", is that you should use right tools for your job. Depending on the complexity of your problem and domain, one or the other design pattern/architectural pattern may perform better. And following that way, in contrast to old frameworks (ZF1, SF1), SF2+ doesn't force you to go for any architectural pattern or organizing your business logic in specific way. You can even put everything outside bundles structure. So the best thing, which you can do, is to try learn more about design patterns (generally). And then, when you need, you will be able to pick one which will work best for your case.
You may want to look at:
mentioned earlier "Patterns of Enterprise Application Architecture", especially chapter: "Domain Logic Patterns".
The Four Architectures that will inspire your programming short review of different architectures.
any of books covering DDD, like: E.Evans "Domain-Driven Design", V.Vernon "Implementing Domain-Driven Design" or S.Millett and N.Tune "Patterns, Principles and Practices of Domain-Driven Design"
Domain-Driven Design in PHP decent book covering implementation of DDD patterns in PHP application, with some examples based on SF.
The Clean Architecture in PHP implementation of The Clean Architecture for PHP, focusing a lot on framework independence (with examples for ZF2 and Laravel).
With Domain Driven Design it creates fat model layers, and also calling a lot of services inside your controller may modularize your code, it still has its own set of challenges, it makes the design harder to create, and at some point there will be too many service calls inside the controller, what can actually be done is to use a few concepts from DDD.
two things to remember before starting DDD is :-
cohesion - modules that change together
coupling - modules that are dependent on each other
You need to lessen the coupling and recognize the cohesion and design the project according to it, main goal is to allow adding and removing or enable/disable/recombining of modules in future, in case you decide to alter the project
instead of having bundles depend on each other use interfaces instead
namespace MyProject\UserBundle\Activity ;
use MyProject\NotificationBundle\Notification;
use MyProject\MailBundle\Mail;
where UserBundle is coupled with NotificationBundle and MailBundle use interfaces that abstract the bundles instead
namespace MyProject\UserBundle\Activity ;
use MyProject\ServiceBundle\NotificationInterface;
use MyProject\ServiceBundle\MailInterface;
Main concepts of DDD are
value objects - an object that holds some data and is passed back and forth and does not focus identity but rather on the data that it holds, value objects can be used in symfony using embeddables
Entity - an object that holds some data but is dependent on an identity value rather than its data value
Repository - use of repository classes to make database operations make it possible to change the implementation later on, as it is centralized to one place
Aggregate - when several object belong together like a number of things that belong to a single category (eg: songs that belong to a genre), the entire collection of objects are treated as one and to make alteration to these objects would be thought on single aggregate object
Domain Events - any change in the state of the domain/data is regarded as an event, in symfony there are Event Listeners and Subscribers which can stand in for domain events, this is one of the most important concepts of DDD, filter also a great deal of improvement to the code
services - services are callable modules of code that do a unit of work, services allow code to be reused and are easier for testing and updating, services in symfony should contain the domain logic and the service layer can get pretty fat, this along with events make the code faster and more maintainable
Factory patter - this patter uses a 'factory' object that generates a different object, by doing this the name of the second object is abstracted, this helps when refactoring the code
these are generalized concepts that need to be applied to code that is highly situational, proper DDD requires the code to be modular which is a challenging task to achieve and need some experience on the engineer's part.
as already stated by others, books by 'martin fowler', ' V.Vernon' design patterns by ' gang of four' etc would be a good read
First of all there are best practices where to place files/components: http://symfony.com/doc/current/cookbook/bundles/best_practices.html.
Secondly http://symfony.com/doc/current/best_practices/business-logic.html:
In Symfony applications, business logic is all the custom code you write for your app that's not specific to the framework (e.g. routing and controllers). Domain classes, Doctrine entities and regular PHP classes that are used as services are good examples of business logic.
So you are not forced to use any architecture for your business logic.
Regarding your question - you can implement objects with operations and declare them as services (or use them directly, but in this case when you want to replace some functionality you'll need to rework more code).
there are always a lot of principles of software designing and we select what we think is more correct and makes more sense for a project and Symfony doesn't force us to use some special design pattern.
I've been learning Yii2 framework for a couple of weeks now. One of its core concepts is "Fat models, thin controllers". Reading the source code of the advanced application template I found that due to this concept nearly all the logic is contained within the models.
Well, there could be no questions at all if I hadn't some experience with Spring MVC where service layer seems to be a kind of natural way to decouple application's logic from its actual data.
So the question is: can it be a good practice to implement such an enterprise-like structure in an application built with Yii2? Speaking more specifically: is it worth breaking Yii's models into Entities, DTOs and Services?
Thank you in advance!
P.S.: The question can seem to be a kind of too abstract or subjective but having little experience with Yii2 I'd like to know are there any architectural features in Yii2 that could make the above mentioned implementation be not optimal in regard to code maintenance, performance and so on?
You can actually create models that are not ActiveRecords, so they actually become your service layer, just need to extend from yii\base\Model or yii\base\Object as you see fit, and implement all the logic you need there. You can also create those models on another folder called services, so their namespace would become app\services\ModelName
Using another feature instead of built-in feature can not be a good practice for every framework.
IMO, the model part is a killer feature of yii2, so if you do not need scaffold (code generation), you can use any other php framework without model part (zf2, symfony2, micro-frameworks).
So you can use your own model architecture without any perfomance lag but you'll need to write more code to make things done and your models will be hard to support by other people that are using yii2 and therefore I recommend to use another framework which comes without model layer.
i got a little bit confused about decoupling, separating of concerns, the framework (Symfony2) and my business model. Let me explain :)
In modern web based projects we're supposed to have a thin controller. This seems to be best practice nowadays. Also it seems to be best practice to decouple the framework and the business model. And to do separation of concerns. I'm fine with all of that. Using events/event dispatching works like a charme to solve these concerns.
But now i have a task where i need to do the following things:
read a cookie
save some data to the database based on the contents of the cookie
delete the cookie
First my understanding of working with cookies in Symfony2:
I read the cookie using the request object
I manipulate the cookie using the response object
I should avoid using \setCookie directly
And that's the point where i got confused. Because:
I would assume that all of the three steps are part of my "task" i need to perform. So it would make sense to do all of the stuff in the same class/piece of business model.
I want to avoid mixing up my business model and third party components (like the request/response) as much as possible.
Now i have two options - But both of them are feeling wrong in some way:
Being strict on decoupling framework and business model - Reading/writing the cookie will be left in the controller, since framework components are involved. The persisting is done in the business model. - BUT: Not all the code belonging to the task are in one place now.
I also could have all of the code necessary to perform the task in one place. But then i would need to make the request and the response available within my service, which i try to avoid.
How do you guys handle this kind of issues ?
Thanks,
Stephan
I suppose that you have to make a choice: if you're trying to avoid injection of the request into a service you have to manipulate it into the controller directly.
Of course you could use a private controller that you can call from an arbitrary action and where you can store all the code: that way you could follow the DRY methodology that is always a good practice and you'll avoid injection.
In my vision of symfony however, I would use a service with injection keeping controllers small and not heavy. In that service you could store all business logic related to controller's object manipulation.
This answer, however, could vary from devel to devel so it's hard to find the right methodology
Regarding decoupling from the framework, I wrote a blog post about that here http://thesolidphp.com/decoupling-application-from-framework/
You could separate the cookie handling by creating your own class that will use the Symfony cookie manager. That class should implement an interface like CookieStorage. Your domain objects will only depend on that interface. A concrete implementation could be SymfonyCookieStorage, that will call the Symfony cookie handling objects. Now your business objects are separated from the Symfony cookie manager.
It's the same concept I wrote about in the blog post. That way you could decouple basically everything and keep you objects unaware they are using Symfony.
Two questions really:
When designing a RESTful web service in an MVC framework like Yii, should we consider the actual JSON or XML returned as a View (which makes sense to me, because rendered pages are views in the RESTful architecture of the web), or some derived property of a fat Model (i.e. Controller->sendResponse(Model::JSONRepresenation());
In Yii specifically, can I substitute other Content-Type idioms (like application/json) and try to wire the Views to make this work? OR is this a foolish endeavor? The Yii guide to RESTful web services does not suggest the approach of mapping endpoint Actions to Views, which is what I would have expected.
The MVC terms are meant to separate code sections, not classify the content sent to the client. So your question is analogous to asking if you should call the REST response a PHP or Perl output? You shouldn't call it either, generically. You can only call it one or the other specifically for your particular implementation. Nonetheless, In the Yii Guide example that you referenced, the JSON/XML "page" requires no separate view file and is sent directly from the controller which formats the model in JSON, per your definition of a "fat Model".
I 'm not familiar with implementing the application/json idiom in Yii, but I can't imagine why you wouldn't follow the pattern in the canonical example provided by the Yii Guide.