-: The next part of the URL
and this is also an optional part, is the sub entity.
Now, what is sub entity?
The sub entity is used for accessing entities
that are dependent on other entities.
And if this sounds a little bit complicated
then I hope the example will help clear things up.
So for example, get all the items of order no. 17.
So in this case, the order is the entity
and the items of the order are the sub entities.
So we will need the URL to specify
that we don't want to retrieve the order itself
but the items of the order and let's see how it's done.
But first let's see how it shouldn't be done.
So a common mistake I see in a lot of organizations
is something like this.
So you see here the APIs
the version and the entity is items in order.
And the number of the order.
This is a mistake and you should not implement
the URL like this.
Why? First it's not very readable.
Notice how long the text part of the URL is.
So you actually need to concentrate to
understand what exactly is going to be retrieved here.
And as a result, this is not simple,
and we always try to make a URL as simple as possible.
So what is the correct way to use the sub entity in the URL?
So the sub entity should come after the ID parameter
and it should look something like this.
So you see here again the API, the version, the entity
the ID parameter, and this is the ID
of the entity and after the ID parameter, the sub entity
the items, in this case.
So when looking at the URL like this
then we see that the URL is hierarchical
and it is very easy to understand we are actually going
from all the entities to a specific entity
to the sub entities of the specific entity.
So what we are having here is a very simple
and very easy to understand URL.
Now, same goes also for sub-sub-entity, etc.
which is not a very common case, but
in theory you can add another ID parameters
after the sub entity and after this ID parameter,
add sub-sub-entity, etc.
Again, not very common, but can be used.
So let's see how the sub entity fits
in the URL that we are building.
Back to our receptor.
All we need to do is add forward slash and items.
So look at what we have here.
We have a GET.
So we understand that this API should return something.
It is retrieving something and what does it retrieve?
It retrieve from the order it goes to order number 17.
And for this specific order
it should return all the items of the order.