REST URL naming convention /items/{id} vs /items?id={id} - url

I understand that in MVC pattern and in REST services it is common to use URIs like /items/{id} but what is bad thing about using query parameters in the URI?
GET /items/{id} vs GET /items?id={id}
Further, lets say an entity has 'referenceId' field that points to some related (say parent) entity, and I need to create REST service to get all items for parent entity, which way is better:
GET(POST) /items/parent/{parentId}
or
GET(POST) /items?parent={parentId}
Will be grateful for insights that would help to resolve my subjective issues on constructing URLs for REST services.

I would use the following schemes.
/items/id
This uniquely addresses a resource of items with id id. We are not using parameters as a parameter to uniquely address this resource (as is the case with the other option). Just as
miguelcobain suggests.
/parent/id/items
Here id is an id to uniquely address a resource of parent and from those we collect/retrieve the items it references. From what you have said in the question it seems that parent references multiple items, like a container or collection.
The convention I use for this is to narrow down the scope going from left to right. Therefore in case items could be active or inactive. Thusly items have a property or attribute to be active or inactive. Narrowing down on this I get the following scheme:
/items/active
/parent/id/active

For your first question:
/items/{id} should retrieve a single resource with the specified id or 404 if it doesn't exist.
/items/?id={id} should retrieve an array (even if only one in the array) because you are querying the collection.
For your second question:
I agree with #miguelcobain's assessment - if the item is a specific resource/entity, just use the proper resource path to retrieve it.
To make this easier on the consumer, create a link header with rel="parent" and/or include the uri in the child resource. For an example of link headers, see GitHub's pagination api.

Of course, REST principles don't care about aesthetic details on URLs. It just imposes that every resource should be uniquely addressable.
Furthermore, using the query parameters to uniquely address something "kind of" violates the semantics of a "parameter", doesn't it? A parameter should be something optional, something additional and parameterized. Something like a detailed search on a collection of items, for example.
What you wrote may make sense in some cases. It depends.
In your example, is the item really a resource? If not, you could just do GET(POST) /parents/{parentId}.
If parent is, say, a boolean, and you want to search the items that have parent equals to true, then using the parameters makes sense. But since you're explicitly saying that you want a parent with a specific id, I assume that parent is a resource itself and I would uniquely address that resource using your option 1.
I hope I made myself clear.

It seems to me there are no rules to follow.
items/{id} - this convention is suitable for GET item by given id. If user doesn't provide id then it returns 404 status code.
items/id={id}&name={name} - this type of convention is suitable for search multiple items by given criteria. If no items are found, it is not a 404 situation, you simply say "I successfully found nothing matching your search criteria"

Related

Possible to select a specific entity without knowing the key in OData?

I have a problem where I need to select a specific value from a specific entity from a entity set, however, I need to do it in a way without knowing the key.
This is the query I actually need:
odata/..../picklistLabels(locale='en_GB',optionId=10819)/label
However I need to program it in a way so it automatically selects the label without knowing the optionId. Is there a way to do this in OData?
From your question, I think that you want to perform a navigation but you don't have a key. Unfortunately, this exact functionality isn't available, however, you can perform an expand like this:
odata/..../picklistLabels?$filter=locale eq 'en_GB' and optionId=10819&$expand=label
This will get you the same information that the other call would do but in a slightly different format, you would have to find the first element in the array and then get the label property to get that information
As an aside, if you have the option to change the server (I'm guessing not due to the sapui5 tag but it might be useful for other users) you could change the key. If the locale and the optionId are enough to identify the object, then you could make these into a composite key. Here is a link for an example within the WebAPI OData source code: https://github.com/OData/ODataSamples/tree/master/WebApi/v4/ODataCompositeKeySample

Which relay objects must implement `Node`?

https://facebook.github.io/relay/graphql/objectidentification.htm is very clear around what Node is and how it behaves, but it doesn't specify which objects must implement it, or what the consequences are if your object doesn't implement it. Is there a set of features that don't work? Are such objects completely ignored? Not all objects in the existing spec (e.g. pageInfo) implement it, so it's clearly not universally required, but pageInfo is somewhat of a special case.
Another way of thinking about the Node interface is that objects that implement it are refetchable. Refetchability effectively means that an object has an ID that I can use to identify the object and retrieve it; by convention, these IDs will usually be opaque, but will contain type information and an identifier within that type (eg. a Base-64 encoding of a string like "Account:1234").
Relay will leverage refetchability in two ways:
Under a process known as "diffing", if you already have some data for an object identified by ID QWNjb3VudDoxMjM0 (say, the name and address fields), and you then navigate to a view where we show some additional fields (location, createdAt) then Relay can make a minimal query that "refetches" the node but only requests the missing fields.
Relatedly, Relay will diff connections and will make use of the Node interface to fill in missing data on those (example: through some combination of navigation you might have full information for some items in a view, but need to fill in location for some items within the range, or you might modify an item in a connection via a mutation). So, in basic pagination, Relay will often end up making a first + after query to extend a connection, but if you inspect its network traffic in a real app you will also see that it makes node queries for items within connections.
So yes, you're right that pageInfo doesn't implement Node, and it wouldn't really make sense for it to do so.

What is the right Uri syntax for multilevel navigation in ODATA?

I have an ODATA Service MyService with entities Customers,Products and Categories, where Navigation Property is defined from Customers to Products, and from Products to Categories.
I am confused about the correct form of Uri to do Navigation from Customer to Product to Categories.
Initially I gave MyService/Customers(1)/Products(10)/Categories, but it gave me an error.
Then I tried MyService/Customers(1)/Products/Categories which worked correctly. I saw many examples in the internet in the form of the uri which I tried initially But it does not work for me.
Can anyone explain about this?
The correct form of URI depends on the multiplicity of the navigation property Products. If a Customer can have multiple Products then the first form is correct. If a Customer can have at most one product then the second form is correct.
Perhaps in your service this navigation property has had the multiplicity set incorrectly.
The use of parenthesis to specify the resource key indicates that this is an OData v4 topic.
According to the specification OData v4: 4.3.3 URLs for Related Entities with Referential Constraints your syntax is compliant as long as Porducts is a collection type.
Include the relevant $metadata for the resources in question in the future to resolve this level of ambiguity.
If your second form of URL worked, then it usually indicates that the multiplicity of the Products navigation property is singular, making it no longer a collection and therefore you cannot filter by the key. In this case, as above you could use the $filter query option, but then you might as well have queried the Categories controller directly.
Even if the syntax is compliant and the resource navigation to Products IS a collection, in many implementations this type of specificity in navigation is NOT supported. Maybe because it is unnecessary but probably because it is a grey area in terms of intent so it is hard for code frameworks to enforce routing conventions or rules in this area by default.
For instance, should this query be evaluated by the Customers controller, but return a collection of Category resource, or should this be evaluated by the Products controller to return a collection of Category resource? Wouldn't it be easier to design the underlying controllers if the Category controller was the one to return and query the Category resources, rather than potentially adding this same support to all of the Customer,Product and Category controllers?
Given that the unique key of 10 has been provided for the expected Product resource to return, the Customer key of 1 is irrelevant.
If you wanted to deliberately return a Product resource with a key of 10, but only if it belongs to a Customer with a key of 1 then you could also specify that query in the following forms:
~/MyService/Products(10)/Categories?$filter=Product/CustomerFK eq 1
~/MyService/Products(10)/Categories?$filter=Product/Customer/PK eq 1
or you can query the Category controller directly:
~/MyService/Categories?$filter=Products/any(p:p/Customer/PK eq 1 and p/Category/PK eq 10)
Whilst service authors can choose to support multi level navigation as the specification suggests and OP has attempted, it is not always offered out of the box and as such we tend to forget to implement it at all. Its not always hard to do, often we just need to implement some simple routes, but due to the variability of the interpretation and implementation, I personally only ever support navigating 1 level deep but do not allow key selector at the child level.
If the service you are querying does not support it, then simply target the Category resources directly through the Cateogry or indirectly through the Product controller with an appropriate filter.

How can an ASP.NET MVC Action method access sub entities of an aggregate root?

I'm having trouble understanding how one would access the sub entities of an aggregate root. From answers to my previous question I now understand that I need to identify the aggregate roots of my model, and then only setup repositories which handle these root objects.
So say I have an Order object that contains Items. Items must exist within and Order so the Order is the aggregate root. But what if I want to include as part of my site an OrderItem details page? The URL to this page may be something like /Order/ItemDetails/1234, where 1234 is the ID of the OrderItem. Yet this would require that I retrieve an Item directly by ID, and because it is not an aggregate root I should not have a OrderItemRepository that can retrive an OrderItem by ID.
Since I want to work with OrderItems independent of an Orders does that imply that OrderItem is not actually an aggregate of Order but another aggregate root?
I don't know your business rules, of course, but I can't think of a case where you would have an orderitem that doesn't have an order. Not saying you wouldn't want to "work with one" by itself, but it still has to have an order, imo, and the order is sort of in charge of the relationship; e.g. you would represent all this by adding or deleting items from an order.
In situations like this, I usually will still require access to the items through the order. It's pretty easy to setup, in URLs I would just do /order/123/item/456. Or, if item ordering is stored / important (which it normally is stored at least indirectly via the order of entry), you could do /order/123/item/1 to retrieve the first item on the order.
In the controller, then, I just retrieve the order from the OrderRepository and then access the appropriate item from there.
All that said, I do agree w/ Arnis that you don't always have to follow this pattern at all. It's a case-by-case thing that you should evaluate the tradeoffs before doing it.
In Your case, I would retrieve OrderItem directly by URL /OrderItem/1234.
I personally don't try to abstract persistence (I don't use repository pattern). Also - I don't follow repository per aggregate root principle. But I do isolate domain model from persistence.
Main reason for that is - it's near-impossible to abstract persistence mechanisms completely. It's a leaky abstraction (e.g. try specifying eager/lazy loading for ORM that lives underneath w/o polluting repository API).
Another reason - it does not matter that much in what way You report data. Reporting part is boring and relatively unimportant. Real value of application is what it can do - automation of processes. So it's much more important how Your application behaves, how it manages to stay consistent, how objects interact etc.
When thinking about this problem, it's good to remember Law of Demeter. The point is - it should be applied only if we explicitly want to hide internals. In Your case - we don't want to hide order items.
So - exploiting fact that we know that entity Ids are globally unique (as opposed to unique only in Order context) it's just a short-cut and there is nothing wrong with retrieving them directly.
Interestingly enough - this can be pushed forward.
Even behavior encapsulation can and should be loosened up too.
E.g. - it makes more sense to have orderItem.EditComments("asdf") than order.EditOrderItemComments(order.OrderItems[0], "asdf").

How can I modify the queryset in the change list view depending on a parameter I set in the URL

My problem is the following and it is related to the change list view of the admin interface.
I have a workorder model with several fields to caracterize the work order.
They are : type, nature, scheduling_type (and others).
When I see the list view, I would like to be able to change the filter (thus be able to create complex ones depending on the values of the different fields of the workorder model - the ones above and dates for example).
I have found post showing how to modify the default queryset (using managers for example) but I can't find a post that will use a value that is given in the url (ex. admin/workorder/planned_corrective). When the parameter planned_corrective is found, it must be used to select the appropriate queryset or manager and render the corresponding list.
As a add on, I want from that list to be able to use the standard admin options (like list filters, search ...) on that query.
Hope it is clear and thanks in advance for your help.
It sounds like you're after a RESTful interface.
You could accomplish much of this just by being clever with your urls.py - ie, defining admin/workoder/planned_corrective and every other possible parameter that could be encoded in the URL.
A lot of this can also be accomplished just by adding a get-absolute-url method to your models.
Or, you could the effort into using something like the django-rest-interface in your app.

Resources