What is the correct restful API design when we have optional behavior?
I have use case where a class of students is broken down into teams.
class has a classId and team has a teamId.
I have the following options:
Create 2 endpoints:
@GET
@Path("/schoolMetadata/byClass/{classId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataByClassId(
and
@GET
@Path("/schoolMetadata/byTeam/{teamId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataByTeamId(
Second implementation would be using query param.
@GET
@Path("/schoolMetadata/by/")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataById(
@QueryParam("classId") final Id classId
@QueryParam("teamId") final Id groupId) {
if (classid != null) {
} else {
}
}
Which of the 2 approaches is better ?
java rest api
asked Nov 19 '18 at 22:12
JavaDeveloperJavaDeveloper
1,93353772
add a comment |
I have use case where a class of students is broken down into teams.
class has a classId and team has a teamId.
I have the following options:
Create 2 endpoints:
@GET
@Path("/schoolMetadata/byClass/{classId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataByClassId(
and
@GET
@Path("/schoolMetadata/byTeam/{teamId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataByTeamId(
Second implementation would be using query param.
@GET
@Path("/schoolMetadata/by/")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataById(
@QueryParam("classId") final Id classId
@QueryParam("teamId") final Id groupId) {
if (classid != null) {
} else {
}
}
Which of the 2 approaches is better ?
java rest api
asked Nov 19 '18 at 22:12
JavaDeveloperJavaDeveloper
1,93353772
add a comment |
I have use case where a class of students is broken down into teams.
class has a classId and team has a teamId.
I have the following options:
Create 2 endpoints:
@GET
@Path("/schoolMetadata/byClass/{classId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataByClassId(
and
@GET
@Path("/schoolMetadata/byTeam/{teamId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataByTeamId(
Second implementation would be using query param.
@GET
@Path("/schoolMetadata/by/")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataById(
@QueryParam("classId") final Id classId
@QueryParam("teamId") final Id groupId) {
if (classid != null) {
} else {
}
}
Which of the 2 approaches is better ?
java rest api
asked Nov 19 '18 at 22:12
JavaDeveloperJavaDeveloper
1,93353772
I have use case where a class of students is broken down into teams.
class has a classId and team has a teamId.
I have the following options:
Create 2 endpoints:
@GET
@Path("/schoolMetadata/byClass/{classId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataByClassId(
and
@GET
@Path("/schoolMetadata/byTeam/{teamId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataByTeamId(
Second implementation would be using query param.
@GET
@Path("/schoolMetadata/by/")
@Produces(MediaType.APPLICATION_JSON)
public Response getMetadataById(
@QueryParam("classId") final Id classId
@QueryParam("teamId") final Id groupId) {
if (classid != null) {
} else {
}
}
Which of the 2 approaches is better ?
java rest api
java rest api
asked Nov 19 '18 at 22:12
JavaDeveloperJavaDeveloper
1,93353772
asked Nov 19 '18 at 22:12
JavaDeveloperJavaDeveloper
1,93353772
edited Nov 19 '18 at 22:21
JavaDeveloper
asked Nov 19 '18 at 22:12
JavaDeveloperJavaDeveloper
1,93353772
asked Nov 19 '18 at 22:12
JavaDeveloperJavaDeveloper
1,93353772
asked Nov 19 '18 at 22:12
JavaDeveloperJavaDeveloper
1,93353772
1,93353772
add a comment |
add a comment |
2 Answers
2
active
oldest
votes
The idea behind RESTful urls is that they should represent 'resources' which are singular or plural nouns. Resources that represent a 'collection' of like things should be plural. You have indicated that school metadata can be obtained for either a class id or a team id. That sound like classes and teams might be considered as 'resources', regardless of whether they are both modeled internally as a 'schoolMetadata'. Without any other information, I might suggest something like:
- classes/{classId}
- teams/{teamId}
If you're using jaxrs, it would natural to wind up with urls that look something a little more like this:
- schoolMetadata/resources/classes/{classId}
- schoolMetadata/resources/teams/{teamid}
You might also want to implement:
schoolMetadata/resources/classes to produce a list of 'classes'. Query params could be used here to facilitate search options.
schoolMetadata/resources/teams to produce a list of 'teams' . . .
answered Nov 19 '18 at 23:11
Tom DrakeTom Drake
43738
Actually, REST says to treat URLs as opaque. There's no such thing as a "RESTful URL". Please don't conflate hackable URL best practices with REST constraints.
– Eric Stein
Nov 20 '18 at 2:54
Eric, have you read Fieldings dissertation. I don't think he agrees with you.
– Tom Drake
Nov 20 '18 at 18:11
I have, in fact. Please point out where in the dissertation it suggests that REST URLs should contain semantically meaningful information for the client? I would also refer you to the horse's mouth: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
– Eric Stein
Nov 25 '18 at 1:27
I've already provided a link to the section which discusses this. It states plainly 'The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities...'
– Tom Drake
Nov 26 '18 at 7:59
The section you're quoting provides no guidance on what a URL should look like. Neither does anyplace else in the dissertation. REST, as defined by Fielding, means you're using HATEOAS and following links, not hacking URLs. Hackable URLs are a convenience for developers. They may or may not be good design, but they are not REST.
– Eric Stein
Nov 26 '18 at 14:12
|
show 3 more comments
I guess the first approach is better because it fits the Single Responsibility Principle (SOLID).
The single responsibility principle (SRP) asserts that a class or module should do one thing only. Now, this is kind of subjective, so the principle is reinforced with the heuristic that the class or module should have only one reason to change.
1 approach has two methods (modules) and each do only one thing
answered Nov 19 '18 at 22:44
RuslanRuslan
1,320515
add a comment |
Your Answer
StackExchange.ifUsing("editor", function () {
StackExchange.using("externalEditor", function () {
StackExchange.using("snippets", function () {
StackExchange.snippets.init();
});
});
}, "code-snippets");
StackExchange.ready(function() {
var channelOptions = {
tags: "".split(" "),
id: "1"
};
initTagRenderer("".split(" "), "".split(" "), channelOptions);
StackExchange.using("externalEditor", function() {
// Have to fire editor after snippets, if snippets enabled
if (StackExchange.settings.snippets.snippetsEnabled) {
StackExchange.using("snippets", function() {
createEditor();
});
}
else {
createEditor();
}
});
function createEditor() {
StackExchange.prepareEditor({
heartbeatType: 'answer',
autoActivateHeartbeat: false,
convertImagesToLinks: true,
noModals: true,
showLowRepImageUploadWarning: true,
reputationToPostImages: 10,
bindNavPrevention: true,
postfix: "",
imageUploader: {
brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
allowUrls: true
},
onDemand: true,
discardSelector: ".discard-answer"
,immediatelyShowMarkdownHelp:true
});
}
});
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f53383391%2fwhat-is-the-correct-restful-api-design-when-we-have-optional-behavior%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
2 Answers
2
active
oldest
votes
2 Answers
2
active
oldest
votes
active
oldest
votes
active
oldest
votes
The idea behind RESTful urls is that they should represent 'resources' which are singular or plural nouns. Resources that represent a 'collection' of like things should be plural. You have indicated that school metadata can be obtained for either a class id or a team id. That sound like classes and teams might be considered as 'resources', regardless of whether they are both modeled internally as a 'schoolMetadata'. Without any other information, I might suggest something like:
- classes/{classId}
- teams/{teamId}
If you're using jaxrs, it would natural to wind up with urls that look something a little more like this:
- schoolMetadata/resources/classes/{classId}
- schoolMetadata/resources/teams/{teamid}
You might also want to implement:
schoolMetadata/resources/classes to produce a list of 'classes'. Query params could be used here to facilitate search options.
schoolMetadata/resources/teams to produce a list of 'teams' . . .
answered Nov 19 '18 at 23:11
Tom DrakeTom Drake
43738
Actually, REST says to treat URLs as opaque. There's no such thing as a "RESTful URL". Please don't conflate hackable URL best practices with REST constraints.
– Eric Stein
Nov 20 '18 at 2:54
Eric, have you read Fieldings dissertation. I don't think he agrees with you.
– Tom Drake
Nov 20 '18 at 18:11
I have, in fact. Please point out where in the dissertation it suggests that REST URLs should contain semantically meaningful information for the client? I would also refer you to the horse's mouth: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
– Eric Stein
Nov 25 '18 at 1:27
I've already provided a link to the section which discusses this. It states plainly 'The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities...'
– Tom Drake
Nov 26 '18 at 7:59
The section you're quoting provides no guidance on what a URL should look like. Neither does anyplace else in the dissertation. REST, as defined by Fielding, means you're using HATEOAS and following links, not hacking URLs. Hackable URLs are a convenience for developers. They may or may not be good design, but they are not REST.
– Eric Stein
Nov 26 '18 at 14:12
|
show 3 more comments
The idea behind RESTful urls is that they should represent 'resources' which are singular or plural nouns. Resources that represent a 'collection' of like things should be plural. You have indicated that school metadata can be obtained for either a class id or a team id. That sound like classes and teams might be considered as 'resources', regardless of whether they are both modeled internally as a 'schoolMetadata'. Without any other information, I might suggest something like:
- classes/{classId}
- teams/{teamId}
If you're using jaxrs, it would natural to wind up with urls that look something a little more like this:
- schoolMetadata/resources/classes/{classId}
- schoolMetadata/resources/teams/{teamid}
You might also want to implement:
schoolMetadata/resources/classes to produce a list of 'classes'. Query params could be used here to facilitate search options.
schoolMetadata/resources/teams to produce a list of 'teams' . . .
answered Nov 19 '18 at 23:11
Tom DrakeTom Drake
43738
Actually, REST says to treat URLs as opaque. There's no such thing as a "RESTful URL". Please don't conflate hackable URL best practices with REST constraints.
– Eric Stein
Nov 20 '18 at 2:54
Eric, have you read Fieldings dissertation. I don't think he agrees with you.
– Tom Drake
Nov 20 '18 at 18:11
I have, in fact. Please point out where in the dissertation it suggests that REST URLs should contain semantically meaningful information for the client? I would also refer you to the horse's mouth: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
– Eric Stein
Nov 25 '18 at 1:27
I've already provided a link to the section which discusses this. It states plainly 'The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities...'
– Tom Drake
Nov 26 '18 at 7:59
The section you're quoting provides no guidance on what a URL should look like. Neither does anyplace else in the dissertation. REST, as defined by Fielding, means you're using HATEOAS and following links, not hacking URLs. Hackable URLs are a convenience for developers. They may or may not be good design, but they are not REST.
– Eric Stein
Nov 26 '18 at 14:12
|
show 3 more comments
The idea behind RESTful urls is that they should represent 'resources' which are singular or plural nouns. Resources that represent a 'collection' of like things should be plural. You have indicated that school metadata can be obtained for either a class id or a team id. That sound like classes and teams might be considered as 'resources', regardless of whether they are both modeled internally as a 'schoolMetadata'. Without any other information, I might suggest something like:
- classes/{classId}
- teams/{teamId}
If you're using jaxrs, it would natural to wind up with urls that look something a little more like this:
- schoolMetadata/resources/classes/{classId}
- schoolMetadata/resources/teams/{teamid}
You might also want to implement:
schoolMetadata/resources/classes to produce a list of 'classes'. Query params could be used here to facilitate search options.
schoolMetadata/resources/teams to produce a list of 'teams' . . .
answered Nov 19 '18 at 23:11
Tom DrakeTom Drake
43738
The idea behind RESTful urls is that they should represent 'resources' which are singular or plural nouns. Resources that represent a 'collection' of like things should be plural. You have indicated that school metadata can be obtained for either a class id or a team id. That sound like classes and teams might be considered as 'resources', regardless of whether they are both modeled internally as a 'schoolMetadata'. Without any other information, I might suggest something like:
- classes/{classId}
- teams/{teamId}
If you're using jaxrs, it would natural to wind up with urls that look something a little more like this:
- schoolMetadata/resources/classes/{classId}
- schoolMetadata/resources/teams/{teamid}
You might also want to implement:
schoolMetadata/resources/classes to produce a list of 'classes'. Query params could be used here to facilitate search options.
schoolMetadata/resources/teams to produce a list of 'teams' . . .
answered Nov 19 '18 at 23:11
Tom DrakeTom Drake
43738
answered Nov 19 '18 at 23:11
Tom DrakeTom Drake
43738
answered Nov 19 '18 at 23:11
Tom DrakeTom Drake
43738
answered Nov 19 '18 at 23:11
Tom DrakeTom Drake
43738
43738
Actually, REST says to treat URLs as opaque. There's no such thing as a "RESTful URL". Please don't conflate hackable URL best practices with REST constraints.
– Eric Stein
Nov 20 '18 at 2:54
Eric, have you read Fieldings dissertation. I don't think he agrees with you.
– Tom Drake
Nov 20 '18 at 18:11
I have, in fact. Please point out where in the dissertation it suggests that REST URLs should contain semantically meaningful information for the client? I would also refer you to the horse's mouth: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
– Eric Stein
Nov 25 '18 at 1:27
I've already provided a link to the section which discusses this. It states plainly 'The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities...'
– Tom Drake
Nov 26 '18 at 7:59
The section you're quoting provides no guidance on what a URL should look like. Neither does anyplace else in the dissertation. REST, as defined by Fielding, means you're using HATEOAS and following links, not hacking URLs. Hackable URLs are a convenience for developers. They may or may not be good design, but they are not REST.
– Eric Stein
Nov 26 '18 at 14:12
|
show 3 more comments
Actually, REST says to treat URLs as opaque. There's no such thing as a "RESTful URL". Please don't conflate hackable URL best practices with REST constraints.
– Eric Stein
Nov 20 '18 at 2:54
Eric, have you read Fieldings dissertation. I don't think he agrees with you.
– Tom Drake
Nov 20 '18 at 18:11
I have, in fact. Please point out where in the dissertation it suggests that REST URLs should contain semantically meaningful information for the client? I would also refer you to the horse's mouth: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
– Eric Stein
Nov 25 '18 at 1:27
I've already provided a link to the section which discusses this. It states plainly 'The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities...'
– Tom Drake
Nov 26 '18 at 7:59
The section you're quoting provides no guidance on what a URL should look like. Neither does anyplace else in the dissertation. REST, as defined by Fielding, means you're using HATEOAS and following links, not hacking URLs. Hackable URLs are a convenience for developers. They may or may not be good design, but they are not REST.
– Eric Stein
Nov 26 '18 at 14:12
Actually, REST says to treat URLs as opaque. There's no such thing as a "RESTful URL". Please don't conflate hackable URL best practices with REST constraints.
– Eric Stein
Nov 20 '18 at 2:54
Actually, REST says to treat URLs as opaque. There's no such thing as a "RESTful URL". Please don't conflate hackable URL best practices with REST constraints.
– Eric Stein
Nov 20 '18 at 2:54
Eric, have you read Fieldings dissertation. I don't think he agrees with you.
– Tom Drake
Nov 20 '18 at 18:11
Eric, have you read Fieldings dissertation. I don't think he agrees with you.
– Tom Drake
Nov 20 '18 at 18:11
I have, in fact. Please point out where in the dissertation it suggests that REST URLs should contain semantically meaningful information for the client? I would also refer you to the horse's mouth: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
– Eric Stein
Nov 25 '18 at 1:27
I have, in fact. Please point out where in the dissertation it suggests that REST URLs should contain semantically meaningful information for the client? I would also refer you to the horse's mouth: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
– Eric Stein
Nov 25 '18 at 1:27
I've already provided a link to the section which discusses this. It states plainly 'The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities...'
– Tom Drake
Nov 26 '18 at 7:59
I've already provided a link to the section which discusses this. It states plainly 'The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities...'
– Tom Drake
Nov 26 '18 at 7:59
The section you're quoting provides no guidance on what a URL should look like. Neither does anyplace else in the dissertation. REST, as defined by Fielding, means you're using HATEOAS and following links, not hacking URLs. Hackable URLs are a convenience for developers. They may or may not be good design, but they are not REST.
– Eric Stein
Nov 26 '18 at 14:12
The section you're quoting provides no guidance on what a URL should look like. Neither does anyplace else in the dissertation. REST, as defined by Fielding, means you're using HATEOAS and following links, not hacking URLs. Hackable URLs are a convenience for developers. They may or may not be good design, but they are not REST.
– Eric Stein
Nov 26 '18 at 14:12
|
show 3 more comments
I guess the first approach is better because it fits the Single Responsibility Principle (SOLID).
The single responsibility principle (SRP) asserts that a class or module should do one thing only. Now, this is kind of subjective, so the principle is reinforced with the heuristic that the class or module should have only one reason to change.
1 approach has two methods (modules) and each do only one thing
answered Nov 19 '18 at 22:44
RuslanRuslan
1,320515
add a comment |
I guess the first approach is better because it fits the Single Responsibility Principle (SOLID).
The single responsibility principle (SRP) asserts that a class or module should do one thing only. Now, this is kind of subjective, so the principle is reinforced with the heuristic that the class or module should have only one reason to change.
1 approach has two methods (modules) and each do only one thing
answered Nov 19 '18 at 22:44
RuslanRuslan
1,320515
add a comment |
I guess the first approach is better because it fits the Single Responsibility Principle (SOLID).
The single responsibility principle (SRP) asserts that a class or module should do one thing only. Now, this is kind of subjective, so the principle is reinforced with the heuristic that the class or module should have only one reason to change.
1 approach has two methods (modules) and each do only one thing
answered Nov 19 '18 at 22:44
RuslanRuslan
1,320515
I guess the first approach is better because it fits the Single Responsibility Principle (SOLID).
The single responsibility principle (SRP) asserts that a class or module should do one thing only. Now, this is kind of subjective, so the principle is reinforced with the heuristic that the class or module should have only one reason to change.
1 approach has two methods (modules) and each do only one thing
answered Nov 19 '18 at 22:44
RuslanRuslan
1,320515
answered Nov 19 '18 at 22:44
RuslanRuslan
1,320515
answered Nov 19 '18 at 22:44
RuslanRuslan
1,320515
answered Nov 19 '18 at 22:44
RuslanRuslan
1,320515
1,320515
add a comment |
add a comment |
Thanks for contributing an answer to Stack Overflow!
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f53383391%2fwhat-is-the-correct-restful-api-design-when-we-have-optional-behavior%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
