I've got an issue with REST naming convention and backend endpoints placement. Let's assume that we have a system which has domain objects like: Product and Survey. Each product has some survey attached to it. Survey is a form which has questions which users fill when they rate the product. I would like to have operation like 'get survey for product with concrete id'. Possible endpoints in my opinion are:
/survey/product/{idProduct}
/product/{idProduct}/survey
More logical and natural is the second option. But now problem is with Controllers. We have ProductController and SurveyController. ProductController is mapped by root URI /product and SurveyController is mapped with /survey URI. So each method which starts with /product should be placed in ProductController, same with /survey.
If we choose second option then we should put concrete method which gets survey for product in the ProductController. But it can be confusing that ProductController serves Survey. It should rather operate on Product. More natural way for developer is that SurveyController returns Survey. It does not matter that ProductController uses SurveyService e.g. to get survey for concrete product. We can always use mapping in SurveyController where we put method which returns survey for concrete product and is mapped by URI /product/{id}/survey but this can be also confusing and time consuming for developer to find method declaration and we cannot annotate controller with some root URI path.
What is better? To use strict convention that URI which starts with e.g. /product is always assigned with ProductController and developer can quickly find method by URI, but method can serve different domain objects, not only Product or to use different URIs with some root path across different controllers?
Problem can look simple if we have few controllers and few domain objects. But what when we consider system with about 100 domain objects?
With 100 domain objects, one has usually some kind of structure for orientation. That means a dependency graph which somewhat dictates how to split the domain, even into separate projects, or separate runnable applications (microservices). So incidentally a larger model actually is "easier".
I would probably think about which resource is at the core of my model. For example if a Product may exists without a survey, but a Survey does not make sense without a Product, I would perhaps make the media-type of Survey link to a Product, rather than the other way. Which would probably look like:
/survey/123 <-- contains link to /product/456
In practice this means that you don't have to actually provide "subresources" like what you proposed.
Related
I have looked at this PUT vs POST question and others on stackoverflow and after going through the answers I found out:
Use POST if server identifies the address of the resource
Use PUT if client know the address of the resource.
Now above works fine if I have a single independent entity. For example if I have Student entity I am admitting a new student to schools I might create a REST endpoint as /api/schools/schools-name/student with POST HTTP method. But once the student has been admitted and I have to make changes to this student I can use Patch/PUT.
But In my case I have dependent entities that is parent and child. First I create parent entity using the POST. Now the child entity is created only after parent entity has been created. Why they can't be created together like after parent entity is created, create the child entity also, is because of business requirement.
Important points to note are that parent and child entity are linked by an id column only. So currently my url for creating child entity is /api/entities/parent-entity-id. Also there is no request body while creating the child entity as all the required info for creating is stored in parent entity.
My question is that should this method be POST as we are creating the
child entity or PUT as I am updating the children of the parent
entity which already has been created?
As mentioned in the question there is no request body for creating a child entity. This api is just to trigger the child entity creation. Parent entity already has all the info.
If you are sending an unsafe request to the server, and it doesn't match the semantics of any of the other HTTP methods, then you should use POST.
In particular, if the message-body is not a candidate representation for the resource identified by the target-uri, then PUT is out of bounds.
The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload
First and foremost, REST is an architecture style used if you need decoupling of clients from servers to allow evolving the server side without risking clients to break. REST isn't a toolset you pick the most suitable things out and leave out the remainder. It is more of an either apply all of the steps and constraints REST proposes or you wont benefit from it thing! For simple back- to frontend communication it is probably to much effort as you are usually in control of both ends, however, if you aren't in control of one end only then you might gain the most benefit of such a design actually.
REST relies heavily on standardized protocols and media types. The interaction model is very similar to the browsable Web, the big cousin of REST. Therefore, the same concepts that apply to the Web also apply to REST. The core idea in both should always be that the server teaches the client on how to do things while clients only take what they are given without trying to deduce further knowledge from either previous interaction or analysis of URIs or the like. I.e. on the Web, HTML forms are used to allow clients to enter certain input that is sent to the server upon clicking a submit button. Both the target URI as well as the method to use are included in that Web form so a client actually doesn't have to care about that fact. Through the affordance of the button element, a client also has the implicit knowledge that a button can be clicked and certain actions may be triggered as a consequence. The same concepts used in the Web should now be used between applications to interact with each other. Here, either HTML forms can be reused or certain, specialized media-types need to be developed (i.e. like hal-forms). Through content-type negotiation client and server can actually agree on a representation format both support and therefore avoid interoperability issues.
One common issue many "REST developer" seem to have is to think of REST endpoints returning certain data to be of certain types, i.e. the data of a company employee or the items of a certain hierarchies. Fielding claims that instead of introducing typed resources meaningful to a client, REST APIs should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and defining application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.
A further thing to mentioned here, which I already striped a bit in my comment, is that URIs don't inherit a parent-child relationship by default. A URI as a whole, including any path, matrix and/or query parameters is just a link to a resource and can be considered as a key used for caches to return a response body previously stored for that key (=URI). Clients therefore shouldn't attempt to deduce semantic knowledge from URIs itself but just use the link relations returned for such URIs. This allows servers to replace URIs down the road while clients still can invoke them based on the name the URI was returned for.
As URIs themselves don't convey any semantic information, they can't really express a parent-child relationship on their own. We humans tend to interpret a URI such as /api/company/abc/employee/123 as expressing that employee with the number 123 is working for company abc, which might be true, but also does not have to be as explained before, URIs lack the semantic of expressing such things. It is only through the utilization of a bunch of such URIs that such a semantic tree can be created.
But In my case I have dependent entities that is parent and child. First I create parent entity using the POST. Now the child entity is created only after parent entity has been created.
If you take a closer look at the HTTP methods you might see that POST requests are processed according to the resource's own specific semantics, meaning that you literally can perform anything you have to here. This is defacto a swiss-army-knife in your toolset available and should be used if the other methods aren't fitting your use-case.
PUT i.e. is specified to replace the current targets representation with the one provided in the payload of the request. However, a server is allowed to validate whether the PUT representation is consistent with any constraints the server has for the target resource and may reject therefore requests to update a certain resource due to conflicts with certain constraints. PUT is further allowed to reconfigure a targets media-type to match a more suitable representation, apply a transformation onto the received payload to convert the payload to a matching one of the target resource or reject the payload in general.
Neither HTTP methods nor URIs can create such a semantic relationship between a parent and child resources. However, this is what link relations are there for! Links are edges between two entities that give a name to the context of the relation between those two entities. Such link relations should be standardized, follow common conventions or represent extension types as defined in RFC 5988 (Web linking) to promote their reusage. Unfortunately, however, IANA does not directly specify a parent and child link relation. up may be used to refer from a child to a parent, in a tree. Through an extension mechanism this is however relatively easy to obtain, i.e. http://api.acme.com/rel/parent and http://api.acme.com/rel/child or something similar.
The next bit to discuss on the quoted segment of the initial post would be happens-before semantics of the creation of the parent in contrast to the child resource. HTTP does not have any kind of transaction semantics nor guarantees of ordering of requests other than outlined in the pipelining section, which only applies to safe methods anyways. HTTP therefore does not give any promises to the processing of requests as they either might not reach the server at all or the response just got lost for whatever reason. Only if the client is receiving a 201 Created response including a Location header pointing to the created resource a client knows for sure that a resource got created and according to the specification only then a client is allowed to create a further child resource.
To a generic HTTP server both the creation request of the parent as well as the consecutive request of creating the child resource are two distinctive requests which it will attempt to fulfill independently. This is the stateless nature of HTTP. As mentioned before though, certain validation of resource's own constraints might be performed preventing the creation of children though.
Important points to note are that parent and child entity are linked by an id column only. So currently my url for creating child entity is /api/entities/parent-entity-id. Also there is no request body while creating the child entity as all the required info for creating is stored in parent entity.
REST doesn't care about your domain model actually. What you have here is a classical example of /persons resources, where three persons are identifiable via separate, distinctive URIs such as /persons/alice, /persons/bob and /persons/joe. We don't know anything about the actual data returned by any of these endpoints actually and by itself, as above mentioned, you can't deduce from the URI directly whose parent of whom (or that any of the URIs actually represents a person to start with). Through link-relation such a context structure can now be given, stating that Bob and Alice are parents of Joe and Joe is a child of both Bob and Alice.
Note how in the example above the actual content of the resources was not of importance to the client. We still don't know if either of the resources contain any information at all. All we know is that there are 3 resources available that are linked to each other in some way. So if the intent of your system is to just represent such relationships than go ahead. Use links between those resources to allow clients to lookup these relationships if interested. If a client is interested in the details of a resource it will send a request for a certain set of media-types to the server anyways. Discoverability and exploration are two common things you will want to guarantee in a REST ecosystem.
My question is that should this method be POST as we are creating the child entity or PUT as I am updating the children of the parent entity which already has been created?
AS POST is an all-purpose tool that has to be used if the other methods aren't fitting, using POST is for sure not wrong. If you take a closer look on the other methods you might see that they serve different purposes, i.e. PUT has the semantics of replacing the current content with the one given in the request payload. It therefore expresses a different use-case than you actually want IMO. As such you should stick to POST also for generating your children.
What you should do within your POST logic, as hopefully was clear enough throughout this answer, is to introduce meaningful link-relations that give the relations between the "entities" some context you can name. Such an operation can further have side effects which allows you to update the parent resource as well and introduce some further links that point from the parent back to the child.
This post is probably already way longer than it needs to be, though I want to make sure that you understand the intent behind REST and when to use it. Unless you really need a system that requires properties such as freedom for evolution, failure robustness and support for the operation of the application/system for decades to come, either exposing your own RPC service or maybe exposing your data model directly is probably easier to obtain.
Also there is no request body while creating the child entity as all the required info for creating is stored in parent entity.
So, this has nothing to do with resource state and therefore nothing to do with REST.
You're not PUTting a new state of a resource, so you should stay away from using PUT.
You are creating a new instance, so you should use POST method on endpoint for previously created parent instance.
Example:
POST /parent/<parent_id>/children/
BODY:
{"json with children data...."}
The ubiquitous language (UL) is used in a whole bounded context, both the domain model and the application layer right? Ok. Then the name of the methods of an application service belongs to the UL. But the arguments of the method, as domain objects shouldn't be expose to the users, won't (cannot) be terms from the UL. If you used UL vocabulary to name method args, then you would be exposing domain objects outside the application.
How do you explain this contradiction about naming application services parameters?
Maybe the question seems a little bit philosophical, but so is DDD, it's a philosophy on software development, and it is based on the UL.
UPDATE
Someone asked for an example, not just philosophy. Well let's say our domain is about a shop selling products. One method of an application service could be:
addProductToShoppingCart ( Product product, ShoppingCart shoppingCart );
But Product and ShoppingCart are entities/value objects of the domain model, and we shouldn't expose it to clients.
So args should be DTOs or primitive types. But such types don't belong to the UL. Product and ShoppingCart do belong to the UL and should be the args of the method, but by doing it you break the rule of exposing domain to clients.
I think the application service layer should strive to reflect the UL as much as it can without leaking details from the domain model technical solution. In other words, you want the application service public API to be expressed using terms of the ubiquitous language, but you do not want the client code to be couple on the domain model layer.
"If you used UL vocabulary to name method args, then you would be exposing domain objects outside the application."
That's a misconception: method arguments should be named using UL terms where you can, but argument types shouldn't leverage types defined in the domain package. This is for technical reasons only as that segregation lets you change the domain model independently from the public application's API.
An example would be much better to discuss than just the "philosophy". But..
The contradiction is that most DDD designs do not in fact follow the UL rigorously enough. Look at almost any publicly available "DDD" design, for example Vaughn Vernon's Github repository.
The "Domain" (i.e. Value Objects and Entities) usually are modeled as data-only "objects", with little if any business logic. Right there the method names already left the UL and are purely in technical terrain (setters, getters usually).
Same with Services. Services are not part of the "Domain" at all. Try telling a business person that you've implemented a PasswordService, I guarantee a blank stare back. Services are also purely technical on the outside, with some business-related methods in them, that could actually belong to some Value Object or Entity.
So, while I agree with the "philosophy" part, the building blocks defined by Eric Evans as used today are far from an optimal implementation of that philosophy.
Take a look at my presentation about exactly this issue: https://speakerdeck.com/robertbraeutigam/object-oriented-domain-driven-design
I'm following these tutorials thoroughly and must say they're great tutorials!
http://www.techchorus.net/create-restful-applications-using-zend-framework
I'm just confused about the whole concept of Zend_Rest abstract methods. In the examples, you only see
index
POST
GET
PUT
DELETE
While these functions make sense, I'm trying to figure out if the whole architecture is only limited to those abstract methods. I'm thinking about a use case where a consumer wants to use the API to update specific fields in lets say the user table, or another case where the consumer wants to update activity table. The business logic of these two tables are covered in one RESTful api controller. I would tackle this problem by creating specific update/post method for each table, and have function parameters to define which fields are being updated. Would this kind of implementation conform with REST and if so how do you go beyond POST,GET, PUT, DELETE methods?
REST architecture does support hierarchical relationships for resources, and your resources are not bound with your database in any way. Your “User” resource might have a subresource “Credentials” that maps to username and password fields in your users table, so you could do a PUT request on “domain.com/users/{userId}/credentials”. You will implement this by creating a controller, say UserCredentials, and the update logic would be in the putAction.
You will have to modify the routing for this to work in Zend though. See How to set up Hierarchical Zend Rest Routes?
Or I don't understand this at all.
I have started my ASP.NET MVC application using the Controller --> ViewModel --> Service --> Repository pattern.
Does every type of object (Customer, Product, Category, Invoice, etc..) need to have it's own repository and service? If so, how do you bring common items together?
I mean there are a lot of the times when a few of these things will be displayed on the same page. So I am not getting this I don't think.
So I was thinking I need a ShopController, which has a ShopViewModel, which could have categories, sub categoires, products, etc. But the problem, for me, is that it just does not seem to mesh well.
Maybe ASP.NET WebForms were for people like me :)
Edit
So would an aggregate consist of say:
Category, SubCategory, Product, ChildProduct, ProductReview with the Product being the aggregate root?
Then in the ViewModels, you would access the Product to get at it's child products, reviews, etc.
I am using entity framework 4, so how would you implement lazy loading using the repository/service pattern?
Does every type of object (Customer,
Product, Category, Invoice, etc..)
need to have it's own repository
You should have a repository per aggregate root in your domain. See this question for more information on what is an aggregate root.
In the example you give I could see a CustomerReposiotry which would handle retrieve all pertinent customer data(Customer has orders a order has a customer). A ProductRepository that handles retrieving product information.
and service? If so, how do you bring
common items together?
A service layer is nice but only if there is added value in adding this layer. If your service simply passes straight into the repository it might not be needed. However if you need to perform certain business logic on a Product a ProductService might make sense.
This might not make sense
public void UpdateProduct(Product product)
{
_repo.Update(product);
}
But if you have logic this layer makes sense to encapsulate your business rules for products.
public void UpdateProduct(Product productToUpdate)
{
//Perform some sort of business on the productToUpdate, raise domain events, ....
_repo.Update(productToUpdate);
}
So I was thinking I need a
ShopController, which has a
ShopViewModel, which could have
categories, sub categoires, products,
etc. But the problem, for me, is that
it just does not seem to mesh well.
If the domain is flushed out the view model ends up making sense
public ActionResult Index()
{
ShopViewModel shopViewModel = new ShopViewModel();
shopViewModel.Products = _productRepo.GetAll();
//other stuff on the view model.
return(shopViewModel);
}
Update
What happens when you also need to
provide data unobtainable from an
aggregate root? For example, say I
have a create Customer view and in
that view, I also need to provide the
user with a collection of Companies to
choose from to associate a new
customer with. Does the collection of
Companies come from CustomerRepository
or would you also need a
CompanyRepository?
If a Company can live by itself (e.g. you edit, update, delete a company) I would suggest a Company is also an aggregate root for your domain (A Customer has a company and a company has a list of Customers). However if a Company is only obtainable via a Customer, I would treat a company as a ValueType/Value Object. If that is the case I would create a method on the customer repository to retrive all CompanyNames.
_repo.GetAllCompanyNames();
Repositories are indispensable, just go with them. They hide out data implementation. Used with an ORM you can pretty much forget about core db activity (CRUD). You'll find generally there's 1:1 map between an object and a repository, but nothing stops a repository returning anything it likes. Typically though you will acting upon an instance. Create non-object specific repositories for your queries that don't naturally fit into an existing one.
You will find a lot of conflicting arguments on the "Services" part of it - which some people like to split between Domain Services (i'd call these business rules that don't comfortably fit into a Core Domain Object) and Application Services (logical groupings of operations on Domain Objects). I've actually gone for one, separate project called [ProjectName].Core.Operations that lives in my [ProjectName].Core solution folder. Core + Operations = Domain.
An operation might be something that returns a DTO of all the information a View requires built via a number of repository calls and actions on the Domain. Some people (myself included) prefer to hide Repositories completely from Presentation and instead use Operations(Services) as a facade to the them. Just go with gut feeling on naming and don't be afraid, refactoring is healthy. Nothing wrong with a HomePageOperations class, with a method GetEveryThingINeedForTheHomepage returns a ThingsINeedForTheHomePage class.
Keep your controllers as light weight as possible. all they do is map data to views and views to data, talk to "Services" and handle application flow.
Download and have a look at S#arp architecture or the Who Can Help Me projects. The latter really shows a good architecture IMHO.
Lastly don't forget one of the major concerns of tiers is pluggability/testability, so I advise getting your head around a good IoC container (I'm a fan of Castle.Windsor). Again S#arp architecture is a good place to find about this.
You can pass more than one type of Repository to the controller (I'm assuming your using some kind of IoC container and constructor injection). You may then decide to compose some type of service object from all of the passed repositories.
When designing a RESTful API should resources which are dependent on others be modeled as sub-uris or should they simply reference each other?
E.g. presuming a door is always dependent on a house then
/house/73/door/1
or
/house/73
/door/1044
where house and door include references to each other?
Most RESTful APIs I have found are quite flat so I would value references to any which do have more complex relationship dependencies.
Regards
In UML terms, if the relationship is that of Aggregation, then you use a flat hierarchy with links between things, whereas if the relationship is that of Composition (i.e., the lifetime of a door is strictly bounded by the lifetime of a house) you use sub-resources.
I'm not suggesting drawing a UML diagram! But it does help to have in mind that distinction. (You could also model the Aggregation case by having sub-resources that are just redirect to the real ones; redirects are RESTful. OTOH, I don't actually like doing that; I prefer to make any relationships explicit and to keep the number of redirects down.)
Just remember that URIs are an implementation detail of the server. If you can model them as flat resources then do so. It will be easier for the server to handle them.
If the identifier for the door is not unique across all houses, then your server is going to need to know the house and therefore you need to include the house in the URI.
The relationships between the resources should be modeled by links within the returned representations. i.e. Your house representation should probably contain links to all of the door resources in that house. I would recommend trying to avoid using the URL structure as having some domain meaning.
Only use a hierarchy if it is needed to uniquely identify the resource.