What is the correct way to create a REST endpoint with a relation

Question

I want to create some endpoints to catch the exceptions for each country, startTime and endTime, but I don’t know what is the right way to structure the endpoints, I talked with my staff and we have different opinions on how to do this:

Parameter 1

• / countries / {countryCode} / exceptions? startTime = {value} & endTime = {value} : get all exceptions for each country for a certain period of time

• / countries / * / exceptions? startTime = {value} & endTime = {value} : get all exceptions in a specific timeframe

Option 2 Query Parameters

• / exceptions? country = {countryCode} & startTime = {value} & endTime = {value} : get all exceptions for each country for a certain period of time

• / exceptions? startTime = {value} & endTime = {value} : To get all exceptions in a specific timeframe

Parameter 3 Path parameters in a different order

• / exceptions / countries / {countryCode}? startTime = {value} & endTime = {value} : To get all exceptions for each country for a certain period of time

• / exceptions? startTime = {value} & endTime = {value} : To get all exceptions in a specific timeframe

All 3 options have pros and cons, but we do not agree that this is best practice. The question is what is the best option for creating these endpoints.

Answer 1

If an exception requires the country to exist, that is, the exception is a subsidiary resource of the country, consider:

/countries/{countryCode}/exceptions?startTime={value}&endTime={value} 

Otherwise, you can manage exceptions as a separate resource:

 /exceptions?country={countryCode}&startTime={value}&endTime={value} 

Answer 2

Path parameters should be used when you show a hierarchy, for example. to show all comments that respond to a blog with id {id}, you would form this endpoint:

 /blogs/{id}/comments 

If you want to filter the comments database on time, you must use the query parameters for this:

 /blogs/{id}/comments?start={start}&end={end} 

In your case, however, on your question, it seems that you have a large list with exceptions. This list can be filtered based on various aspects:

• A country
• Time

Since these properties are not part of the structural hierarchy (based on the context of your question), but simply properties that provide more information about exceptions, it would be wise to catch them as query parameters for filtering, as such

 /exceptions?country={countryCode}&startTime={value}&endTime={value} 

Answer 3

Option 2 , where Exception is a separate first-level object, and the endpoint accepts a country code optional , since the filtering property makes the most sense based on a limited description of your requirements.

Answer 4

It will be difficult for you to choose which answer is correct, most answers seem to indicate that your option 2 is the right choice :)

As far as I know, the fewer problems with the REST architecture, the better it was to take into account that each resource has only these forms that return a list (possibly filtered) or a resource:

 /mainResources /mainResources/:id 

And that /mainResources/:id/:relatedResources is an alias /relatedResources?mainResourceId[]=... (returns a filtered list)

Your option 2 gives you the freedom to add additional relationships such as /exceptions?country={countryCode}&anotherResource={anotherResourceId}&startTime={value}&endTime={value}

Your other options are not incompatible if you consider them to be pseudonyms.

---

Another reason I can think of using URLs such as /mainResource/:id/subResource would be in the case of a denormalized relation such as:

 { 'attribute1': 'value1' 'attribute2': 'value2' 'attribute3': 'value3' 'subResource': { 'attribute4': 'value4', 'attribute5': 'value5' } } 

then this url could return this sub-resource:

 { 'attribute4': 'value4', 'attribute5': 'value5' } 

But this is just data filtering. And, considering your case, the exclusion from the country of exceptions would be inconvenient.