I've been developing for many years and a common problem I face is how best to separate out the service layer. I've been using the repository pattern mainly, but I still struggle with this common scenario.
Customer service that returns a single customer.
Invoice service that returns a list of invoices by customer.
The consumer of the service sometimes wants just a Customer other times they want the customer and the invoices which is fine to leave as two calls.
But a new requirement may be they want the Customer, but also want the total number of invoices the respective customer has.
I do not want to corrupt the GetCustomer method and do not want to return a list of invoices and have them do a count (this would work). Is there a best practice without getting into create a lot of one of methods while still keeping performance and round trips in mind? I see a lot of designs where there will get GetCustomer, GetCustomerDeepLoad, etc.
thanks.
It's simple. Don't overthink it.
Services need to meet the needs of the clients. If the client wants customer details, the service sends a representation of customer details and nothing more; if the client wants a customer and all their orders, the service obliges; and so on. In doing so, you might need more than just a Customer object; for example, you might need a CustomerOrderList object made up of CustomerOrderItem, etc.
What you MUST NOT do is mix the concerns of order management and customer management, meaning that the CustomerOrderItem that you return will be a version suited for customer management and not the full-fledged OrderItem that would be modelled for order management.
That's the reason why I have switched to CQRS. Operations (writing/commands) often targets a single entity type while reads (queries) often want a composition of entities.
You dont want to get those queries into the repositories as the repositories tend to get leaky abstractions when you do that.
In your case you can have two types of services: Entity services which are responsible of taking care of changes and query services which are responsible of taking care of supplying information to the client (composition of different entities).
I typically use repositories only on the write side and let the query services query the database directly. That works as you have your business logic contained in the entity services.
Related
I have a question regarding how to structure my controllers.
Let's assume I have a have a system that has stores and products and stores have products.
so the way to get stores is /api/stores/{id} and the way to get a product is /api/product/{id} or /api/stores/{id}/product/{id}.
How would you structure the Controllers? should I have a controller for products and controller for stores and every route that starts with stores in it should reside in StoresController otherwise in ProductsController?
This is from Microsoft: Api design guidance
In more complex systems, it can be tempting to provide URIs that enable a client to navigate through several levels of relationships, such as /customers/1/orders/99/products. However, this level of complexity can be difficult to maintain and is inflexible if the relationships between resources change in the future. Instead, try to keep URIs relatively simple. Once an application has a reference to a resource, it should be possible to use this reference to find items related to that resource. The preceding query can be replaced with the URI /customers/1/orders to find all the orders for customer 1, and then /orders/99/products to find the products in this order.
This is an issue we have ran into multiple times now... very much looking forward to others' opinions!
Scenario Description (for illustration purposes):
Somebody visits our website, perhaps they fill out some forms, whatever. To us, this person is a prospect/lead. They have not been fully onboarded as a customer; they are simply a potential future customer.
Certain actions can be performed on these Prospects, such as adding certain data to their profile. Let's call this add_foobar_data. Of course, if they become a real customer (somebody consuming our service), we still need to be able to add/remove said data from their account.
Scenario (tl;dr):
Prospects can become Customers
Mutation add_foobar_data conceptually applies to both Prospects and Customers
Prospects only have a subset of data of Customers (they are a true subset; currently Customers have a lot of non-nullable fields Prospects do not have)
Options:
Create a union type, e.g. Customerable. add_foobar_data would return a Customerable (or backref to a Customerable) rather than a specific type.
Create separate mutations for modifying Prospects and Customers (add_foobar_data_to_prospect, add_foobar_data_to_customer)
Everybody is a Customer! Make all those non-nullable fields on Customer that are not in Prospect nullable and add a new flag called isProspect (or isDraft if we want to change how we think about the flow).
Perhaps some other approach I did not think of...
Anybody have thoughts on what is the best approach to this situation and why?
Ended up using an Interface since Prospect is a direct subset of Customer, and not by coincidence.
Ok, my last question had no answers, so I've the doubt that I'm walking on the wrong way.
I'm developing some Web REST Api for a mobile application, and regarding REST best pratices I don't know how to face a many-to-many relationship.
I have two tables, Wallets and Cateories, between these tables there is a many to many relationship since a category may be associated to different wallets and a wallet may own different categories.
Actually this database is used by a non rest website:
when a user creates a new category, he choose from the list of his own wallets which wallets to connect it to, and with this single POST call the category is created and conneted to the wallets.
I don't think that replicating this behaviour is compliant to REST best pratices.
My first idea was to "expose" the connection between categories and wallets with this form:
http://localhost:8000/categories/77/wallets/4
but I had the problem I wrote on my previous question, and I don't think this is the right way.
Anyone has a valid method to manage a many-to-many realtionship according with REST best pratices?
Thanks in advance.
Namespacing wallets by a category is fine, as in /categories/77/wallets/4. You can also consider a more concise scheme like /categories/77/4 or /wallets/77/4 if there are only wallets in a category.
However, you don't have to namespace. Your wallets presumably have their own IDs, so you could also just expose them as /wallets/4.
Is it worth the effort? I think it can be a good practice if your URLs are also on a public website (in which case you would probably want to support slug IDs as well, e.g. /categories/luxury/wallets/acme). If not, you should be aware it will be a little more configuration work on the server-side and a little more work for clients (clients will have to be aware of 2 IDs instead of 1).
We are creating api on employee manage app. So there is schedule in interface, where we have to show all shifts in table, for every user per row. Farther, there is summary for every user (per row) and day (per column). Should we create one big aggregate call like:
GET /api/locations/{id}/shedule
which will return all employees, shifts, summaries etc. Or maybe should we smash that to several collections like:
GET /api/locations/{id}/shifts
GET /api/locations/{id}/events
GET /api/locations/{id}/summary
GET /api/employee/{id}/summary?date_from={date_from}&date_from={date_to}
For me, second option is more flexible and there is no reason to create new abstract resource, which is shedule. In my opinion it is clearly part of interface layer and should not affect on API design.
On the other hand the big aggregate is more optimal, becouse there will be less database calls and it's easy to cache.
How do you think? Is there any source, kind of article, which can I rely on?
There's nothing RESTful or unRESTful about either approach. The semantics of URIs is irrelevant to REST. What really matters is how the clients obtain the URIs. If they are looking up URI patterns in documentation and filling up values instead of using links, the API is not RESTful.
With that in mind, I'd say the approach that is more consistent with your business and your ecosystem of applications is the best one. Don't be afraid to create aggregate resources if you feel the need to.
We have an app which is exposing a RESTful API to a UI for purchasing an item. I have a question regarding API design. Lets say the following action should be taken in order
Item to be chosen for purchase
Next give the address to be delivered to
My question is: should we design a single API which gets both data perform both? Or should we design two API calls - one that creates a purchase record and second that update the address to be delivered to?
The recommended SOA approach is to choose coarse-grained services, which would seem to argue the minimum amount of API calls.
However, from a business point of view, item selection and purchase and item delivery are two very different concerns that should be separate components in your architecture. For item selection, you need to consider things like inventory and pricing. For delivery address, you need to consider user address lists, address validation, shipping, and taxation.
Those two components are not likely to interact much except maybe some external association between an item id and address id. For this reason, I'd recommend two API calls. Functionally, this would also allow your API users do things like update the delivery address without re-purchasing an item, send the bill to one address and the item to another address, etc.
As you state that you design a RESTful API you usually start by designing resources instead of the intended calls. Later on, resource representations can be chosen that include other resources for optimised HTTP request counts.
You might want to choose to proceed the following way:
Model the item list resource (GET - lists all items, POST - allows item creation) /items/
Model the address list resource /addresses/
Model the item instance resource /items/item/resourceId
Model the address instance resource /addresses/address/resourceId
Now all of your resources are available you can think about usage patterns. All your resources are generically available and can be mashed up.
Possible approaches to answer your questions would be:
Extend the item instance resource with the needed address details (coarse grained as lreeder stated)
Model a resource /deliverydetails/ as list and instance resource containing item(s) and address, make the deliverydetails to be queried by item id or whatever your use case fits best
Hope that helps!
Btw. you are automatically following SOA approaches with a Resource Oriented Design. Interfaces will be naturally fitting your business requirements and generic enough to support more advanced use cases.
Here is a good example