Excuse the incorrect terminology on this one....
So, we are heavily using breeze in our application to work with our REST resources, and for the most part is fine.
However, we are typically using the following pattern as a standard:
/entity/{entityId}/anotherEntity/{anotherEntityId}/andAnotherEntity
Defining everything in meta data, we use navigation properties and foreign keys to bind this altogether, and works beautifully. We also extend the Breeze Labs Abstract REST DataServiceAdapter in our application.
But, we are now thinking, that to keep the API in a cleaner shape, we may want to 'group' some of the resources into more logical places.
This would then mean the pattern would look something like:
/entity/{entityId}/entitySpecificGrouping/anotherEntity/{anotherEntityId}/andAnotherEntity
So, my questions here:
Should we even try and do this? Is it RESTful?
How do we go about this in Breeze meta data?
I appreciate any input on this matter.
Related
We have scheme like:
class Entity:
pass
class BigEntity(Entity):
pass
class RedEntity(Entity):
pass
Which way to represent them in REST is better:
Create endpoint like /entities/ and put entity type in request?
Create endpoints like /entities/red/, /entities/big/? How to deal with list of all entities in this case?
You should choose a solution that makes it feel clean for you. There is no magic solution.
I wouldn't recommend using /entities/red/ and /entities/big/ because as a developer you expect /entities/{id} and not /entities/{type}.
You could use query parameters like /entities?type=red. It's clean too but maybe will be harder to maintain in your controllers.
Another solution might be /red-entities/, /big-entities/, /entities. It's clean, understandable and maintainable. It's the solution I prefer.
At the end of the day it really depends what feels cleaner and best understandable to you.
REST design is mostly about depicting your resources in a structure like format. Both the options provided by you are fine depending on the requirements of your API.
If you have a lot of different types of entities (red, big, etc.) I would prefer /entities?type=red. For this your structure would be something like /entities/entity-id
If you don't have a lot of types to deal with (red, big, etc.) and you don't plan on introducing a lot more then it might be better to go with /entities/red. For this structure your entities as /entities/red/entity-red-id
I'm writing an API with spring boot, trying to keep it restful but the structure is quite nested. So say I have:
/api/examboard/{ebid}/qualification/{qid}/subject/{sid}/module/{mid}/
I have a controller for every noun that will take in all Id's, the problem with this is that I don't really need an ebid or a qid for modules, they only really need to be concerned with subjects most of the time. The mapping between them all is quite simple. An examboard will have many qualifications, a qualification will have many subjects etc....
Now the problem is say I go for a simpler API design where I only need the parent Id so the Subject controller will also have:
api/subject/{sid}/module
then I need to include multiple services in my controller based on the way JPA works. As I need to include SubjectEntity based calls and ModuleEntity based calls. However I want to maintain a one to one relationship between my controllers/services and services/repositories. This is why I opted for the longer url as I've mentioned above, but it does seem like overkill. Does anyone have any advice on how I should structure an API like this, most examples are quite small and don't really fit.
Without knowing more about your models and the relations between them, this answer will have to stay a bit diffuse.
First of all - "it depends". I know, but it really does. The way you should design an API depends heavily on your use cases that will define required access patterns. Do you often need all modules for a subject? Then introduce /subjects/{sid}/modules, if you need the details for a module of a subject in a qualification in an examboard - by all means have a /examboards/{ebid}/qualifications/{qid}/subjects/{sid}/modules/{mid}
As you say there are many relations between your entities. That is fine, but it does not mean that you need your API to capture each of these relations in a dedicated endpoint. You should distiguish between retrieving and modifying entities here. Find below examples for certain operations you might want to have (not knowing your models, this may not apply - let's consider this an illustration)
Retrieve qualifications for an examboard
GET /examboards/{ebid}/qualifications plain and simple
GET /qualifications?ebid={ebid} if you feel you might need sophisticated filtering later on
or create a new qualitication for an examboard
POST /examboards/{ebid}/qualifications with the details submitted in the body
POST /qualifications with the details submitted in the body and making the associated examboard ebid part of the submitted data
or update an existing qualification
PUT /qualifications/{qid} (if this operation is idempotent)
POST /qualifications/{qid} (if it should not be considered idempotent)
or delete qualifications
DELETE /qualifications/{qid} deletes entities, cascade-deletes associations
DELETE /examboards/{ebid}/qualifications clears all qualifications from an examboard, without actually deleting the qualification entities
There are certainly more ways to let an API do all these things, but this should demonstrate that you need to think of your use cases first and design your API around them.
Please note the pluralisation of collection resources in the previous examples. This comes down to personal preference, but I tends to follow the argumentation of Sam Ruby in RESTful Web Services (available as PDF) that collections should be first-class citizens in an API
Usually, there should not be a reason to have 1:1:1 relationships between controllers, services and repositories. Usually, this is not even possible. Now, I don't know the reason why you might want to do this, but following through with this will force you to put a lot of logic into your database queries and models. While this (depending on your setup and skills) may or may not be easily testable, it certainly shifts the required test types from unit (simpler, usually faster, more fine-grained) to integration tests (require more setup, more complex, usually slower), when instead of having the bulk of your business logic in your services you put them into many joins and subselects in your repositories.
I will only address your REST API structure question.
As you already pointed out
The problem with this is that I don't really need an ebid or a qid for modules, they only really need to be concerned with subjects most of the time
You need to think of your entities as resources if your entity can stand for itself give it its own top level resource. If instead your entity exists only as a part of another entity build a subresource below its parent. This should correspond with the association type aggregation and composition in your object model design.
Otherwise every entity that is part of a many relationship should also be accessible via a subresource on the other side of the relationship.
As I understood you you have a OneToMany relationship between examboard and qualification so we get:
api/examboards/{eid}/qualifications
api/qualifications/{qid}/examboard
Yo could also remove the examboard subresource and include it in the qualification response.
For ManyToMany realtionships you need two subresources:
api/foos/{fid}/bars
api/bars/{bid}/foos
And another resource to manipulate the relationship itself.
api/foosToBars/{fid}+{bid}
Or likewise.
I am struggling with how to understand the correct usage of models. Currently i use the inheritance of Db_Table directly and declare all the business logic there. I know it's not correct way to do this.
One solution would be to use Doctrine ORM, but this requires learning curve and all the current components what i use needs to be rewritten paginator and auth. Also Doctrine1 adds a another dozen classes which need to be loaded.
So the current cleanest implementation what i have seen is to use the Data Mapper classes between the so called model and DbTabel. I haven't yet implemented this as it seems to head writing another ORM. But example could be something this: SQL table User
create class with setters, getters, business logic here /model/User.php
data mapper /model/mapper/UserMapper.php, the funcionality is basically writing all the update, save actions in here.
the data source /model/DbTable/User.php extends the Db_Table_Abstract
Problems are with relationships between other models.
I have found it beneficial to not have my models extend Db_Table, but to use composition instead. That means my model 'has a' Db_Table rather than 'is a' Db_Table.
That way I find it much easier to reference multiple tables in the same model, which is a common requirement. This is enough for a simple project. I am currently developing a more complex application and have used the Data Mapper pattern and have found that it has simplified my code more than I would have believed.
Specifically, I have created a class which provides all access to the database and exposes methods such as getUser() etc.. That way, if the DB changes, or my client wants something daft like storing records in XML or we split the servers or something I only have to rewrite one class.
Again, my models do not extend this class, but have an instance of it assigned as a property during construction.
I would say the 'correct' way depends on the situation. Following the YAGNI and KISS principles, it is not good to over-complicate your model setup unless you really believe that it will benefit you in the long run.
What is the application you are developing? How is your current setup of extending Db_Table holding you back?
I’m currently working on a prototype of a medium size web application, and I thought that it would be good to also experiment with Entity Framework. The problem is that the major part of the application is not the data layer and logic, and so that I don't have much time to play with Entity Framework. On the other hand, the database schema is quite simple.
One of the problems I’m facing is that I cannot find a consistent way to "write queries". As far as I can tell, there are four "interfaces" for the job:
LINQ to Entities
LINQ to Entities using LINQ extension methods
Entity SQL
Query builder
OK, the first two are essentially the same, but it’s good to use just one for maintenance and consistency.
I’m mostly puzzled by the fact that none of them seems to be complete and the most general. I often find myself cornered and using some ugly looking combination of several of them. My guess is that Entity SQL is the most general one, but writing queries using strings feels like a step back. The main reason I’m experimenting with something like Entity Framework is that I like the compile time checking.
Some other random thought / issues:
I often also use the ObjectQuery.Include() method, but again it takes a string. Is this the only way?
When to use ObjectQuery.Execute() (vs. ToList())? Does it actually execute the query?
Should execute queries as soon as possible (e.g. using ToList()) or should I not care just let leave the execution for the first enumeration which gets in the way?
Are ObjectQuery.Skip() and ObjectQuery.Take() available only as extension methods? Is there a better way to do paging? It’s 2009 and almost every web application deals with paging.
Overall, I understand there are many difficulties when implementing an ORM, and often one has to compromise. On the other hand, the direct database access (e.g. ADO.NET) is plain and simple and has well defined interface (tabular results, data readers), so all code - no matter who and when writes it - is consistent. I don’t want to faced with too many choices whenever writing a database query. It’s too tedious and more than likely different developers will come up with different ways.
What are your rules of thumbs?
I use LINQ-to-Entities as much as possible. I also try and formalise to the lambda-form, as opposed to the extended SQL-style syntax. I have to admit to have had problems enforcing relationships and making compromises on efficiency just to expedite my coding of our application (eg. Master->Child tables may need to be manually loaded) but all in all, EF is a good product.
I do use EF's .Include() method for lazy-loading, which as you say, does require a string input. I find no problem with this, other than that of identifying the string to use which is relatively simple. I guess if you're keen on compile-time checking of such relations, a model similar to: Parent.GetChildren() might be more appropriate.
My application does require some "dynamic" queries to be performed, though. I have two ways of meeting this:
a) I create a mediator object, eg. ClientSearchMediator, which "knows" how to search for clients by name, etc. I can then put this through a SearchHandler.Search(ISearchMediator[] mediators) call (for example). This can be used to target specific data structures and sort results accordingly using LINQ-to-Entities.
b) For a looser experience, possibly as a result of a user designing their own query (using high level tools our application provides), eSQL is ideal for this purpose. It can be made to be injection-safe.
I don't have enough knowledge to address all of this, but I'll at least take a few stabs.
I don't know why you think ADO.NET is more consistent than Entity Framework. There are many different ways to use ADO.NET and I've definitely seen inconsistency within a single code base.
Entity Framework is currently a 1.0 release and it suffers from many 1.0 type problems (incomplete & inconsistent API, missing features, etc.).
In regards to Include, I assume you are referring to eager loading. Multiple people (outside of Microsoft) have developed solutions for getting "type safe" includes (try googling something like: Entity Framework ObjectQueryExtension Include). That said, Include is more of a hint than anything. You can't force eager loading and you have to always remember to call the IsLoaded() method to see if your request was fulfilled. As far as I know, the way "Include" works is not changing at all in the next version of Entity Framework (4.0 - to ship with VS 2010).
As far as executing the Linq query as soon as it's built vs. the last possible moment, that decision is situational. Personally, I would probably execute it as soon as it's built for the most part unless there was a compelling reason not to, but I can see other people going the opposite direction.
There are more mature ORMs on the market and Entity Framework isn't necessarily your best option. For the most part, you can bend Entity Framework to your will, but you may end up rolling your own implementation of features that come out of the box with other ORMs.
I have been reading up on multiple PHP frameworks, especially the Zend Framework but I am getting confused about the proper way to go forward.
Zend Framework does not use ActiveRecords but instead uses the Table Data Gateway and Row Data Gateway pattern, and uses a DataMapper to map the contents of the Row Data Gateway to the model, because ActiveRecord breaks down when your models don't have a 1:1 mapping to your database tables. There is an example of this in the Zend Quickstart guide.
To me, their example looks very bloated with a ton of getters and setters all over the place. I came across various blog posts about Domain Driven Design arguing that using so many getters and setters is bad practice because it exposes all the inner model data to the outside, so it has no advantage over public attributes. Here is one example.
My question: If you remove those getters and setters, how will you render your views? At some point the data has to hit the view so you can actually show something to the user. Following the DDD advice seems to break the separation between M and V in MVC. Following the MVC and Zend example seems to break DDD and leaves me typing up a whole lot of getters, setters and DataMappers for all my models. Aside from being a lot of work it also seems to violate DRY.
I would really appreciate some (links to) good examples or more information about how it all fits together. I'm trying to improve my achitecture and design skills here.
Using Value Objects, you can eliminate some of those public setter methods. Here's a description of the difference between Entity and Value Objects. Value Objects are immutable and often tied to an Entity. If you pass all values in with the constructor, you don't need to set these properties from external code.
Something extra, not directly related to an answer, but more focused on DDD:
(Disclaimer: The only thing I know about the Zend Framework is what I read in the linked article.) The Zend Framework is using DataMappers instead of Repositories. Is this really DDD-ish? Well, Fowler's interpretation of a Repository might say no. However, Eric Evans states that a DDD Repository can be very simple. At its simplest, a Repository is a DataMapper (See DDD book). For something more complex and still DDD, see the Fowler article. DDD has a conceptual Repository that may differ from the pattern definition.
I urge you to continue reading about Domain-Driven Design. I think there's a flaw in the assumption that getters and setters violate DDD. DDD is about focusing on the domain model and best practices to accomplish that. Accessors are just a minor detail.
You don't need to implement all the getters/setters, you can use__get() and __set(). What's the problem then?
From my reading of the post, the question is more philosophical rather than practical.
I don't have the time to write in depth, but here is my two cents. While I agree that you want to limit the number of get and set requests because a class should hide its internals, you also need to take into account the Java and PHP are different tools and have different purposes. In the web environment your classes are being built and taken down with each request and therefore the code you write should not depend on huge classes. In the article you pointed out the author suggests placing the view logic in the class. This probably does not makes sense on the web since I will likely want to present the view in multiple formats (rss, html, etc...). Using accessor methods (get & set) therefore is a necessary evil. You still want to use them thoughtfully so that you don't shoot yourself in the foot. The key is to try to have your classes do the work for you instead of trying to force them to do work externally. By accessing your properties with a method instead of directly you hide the internals which is what you want.
Again, this post could use some examples, but I don't have the time right now.
Can someone else provide a few examples of why accessor methods aren't evil?
There are two approaches here: What I call the "tell don't ask approach", and the other is the ViewModel/DTO approach.
Essentially the questions revolves around what is the "model" in your view.
Tell don't ask requires that the only way an object can be externalized, is from the the object itself. In other words, to render an object, you would have a render method, but that render method would need to talk to an interface.
Something like this:
class DomainObject {
....
public function render(DomainObjectRenderer $renderer) {
return $renderer->renderDomainObject(array $thegorydetails);
}
}
In the context of Zend Framework, you can subclass Zend_View and have your subclass implement this interface.
I've done this before, but its a bit unwieldy.
The second option is convert your domain model in to a ViewModel object, which is like a simplified, flattened out, "stringed out" view of your data, customized for each specific view (with one ViewModel per view), and on the way back, convert the POST data to an EditModel.
This is a very popular pattern in the ASP.NET MVC world, but its also similar to the class "DTO" pattern used to transfer data between "layers" in an application. You would need to create mappers to do the dirty work for you (not unlike a DataMapper, actually). In PHP 5.3, you can use reflection to change private properties, so your DomainObject doesn't even need to expose itself either!
Implementing getters and setters has two advantages, in my eyes:
You can choose which properties to make public, so you don't necessarily have to expose all of the model's internals
If you use an IDE with autocomplete, all the available properties will be a TAB away when you start typing "get" or "set"—this alone is reason enough for me.