Great article, Thanks a lot

Hi! Thanks for the article. I have one question: why do you use term URI in your article, if many of the points in it make sense only for URLs?
https://tools.ietf.org/html...

         foo://example.com:8042/over/there?name=ferret#nose
         \_/   \______________/\_________/ \_________/ \__/
          |           |            |            |        |
       scheme     authority       path        query   fragment
          |   _____________________|__
         / \ /                        \
         urn:example:animal:ferret:nose 

Basically are you correct, it is more accurate to say URLs. URIs identify and URLs locate and in terms of REST, URLs are definitely the more correct to be used. However, locators are also identifiers, so every URL is also a URI - So I am not that way off (there are URIs which are not URLs)

Thanks for pointing that :)

Thank you for your reply. But URNs which are basically universal global ids, are also URIs. Resources, paths, endpoints are basically locations.

awesome

I think one more rule may be needed to make sure path part in URI does not indicate an operation. For example, one should not design URIs such as the following:

http://api.example.com/blog...
http://api.example.com/blog...
http://api.example.com/blog...

which indicate operations on URIs rather than the URIs themselves.

I think there's alot of value in

http://api.college.com/stud...
http://api.college.com/stud...

if you support actual content negotiation. It makes it far easier for poking in a web browser instead of having to fire up postman, curl, or modheader. (as long as the extension in this situation is optional)

Thanks for the post, not really thought about this before so glad I found this on HN

When doing something like `student/1245/courses` there will certainly be a scenario where you want a list of courses on their own as well.
If planning ahead, does that warrant designing your route such as:
`/courses` where you get a list of courses and `/courses?studentId=12345` Where you get courses scoped to a student...
Or is it better to just recreate a separate route such that you have /courses AND student/2345/courses?
Im concerned that the latter results in duplication of code and possibly more confusion (ie not clear if the API require POST to /courses or /student/12345/courses to create a course for a student ) while the former results may cause (lack of) caching problems.
Suggestions?

Hi,

I think that you example is about Courses and not Students.
When you will do '/courses' you will get a list of all available courses, when you do '/courses?studentId=12345' it is basically the same as '/student/12345/courses'.

I java you can point 2 paths to same method, hence no duplication is needed. You will just need to catch both the queryString and the path ID of the student.

All depends on your implementation, but you can allways do:
[/courses?student=12345]
return getCoursesByStudentId(12345);

[/student/12345/courses]
return getCoursesByStudentId(12345);

this will not cause code duplication.

I also think that some web servers can have the ability to cache per query string parameters as well.

Hope that helps,
Guy

I agree. There should be nothing wrong with the two routes executing the same function. Just two ways for the devs to find the same resource.

I have been in developing RESTful services for quite a few years, and learn that nested url can create problem specially when they have many-many relationship like the student and course and building the lengthy URls created the problem. Those URLs were hard to document and created confusion. Here there are only two resources but in my projects there were many resources having many-to-many relationship. I finally ended up changing all the url with query parameter(?studentId= or ?courseId=.) That resolved many of the issue and were really easy to document. Also I hide, the way these services talk to each other.

I know this is a factor in API design, but it shouldn't be. Go watch https://youtu.be/pspy1H6A3FM it has some good information.

Hi,

Thank you for the link, a very nice video.
At minute 17 I see that he is talking about "What makes a URI "RESTful", but I see almost no relation to what the article is about. I am giving general guidelines that you need to consider when building you RESTful API.

Guy

No problem. I guess I took the content in the video slightly differently. I would argue, the format of the URL in a REST API is essentially irrelevant. There are NO rules, and as you pointed out, it just needs to be consistent (as per the API producer). Perhaps if your post was not advocating rules, I wouldn't even comment... That's the link I made with your article anyway.

"The naming authority that assigned the resource identifier, making it possible to reference the resource, is responsible for maintaining the semantic validity of the mapping over time (i.e., ensuring that the membership function does not change)." - Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000.

REST implementations are not even that practical. Are you using hypermedia? Can I discover your whole set of resources from a base URI? Are you versioning your resources rather than your APIs? Are you essentially using it as a convenient HTTP-style RPC?

All these questions don't even matter, since REST is nothing more than an academic ideal.

What does matter, is making people believe there is some 'right' way to do it. I think that can cause more harm than good.

But I am totally stoked you found a way to build RESTful URIs which make sense to you. That's half the challenge.

Good post, the only one I disagree on is the pluralisation rule. /foo and /foos are both valid endpoints with different meanings; the former is a single resource that is a foo, the latter referring to a single resource that is a collection of "foos". And although the latter is a rarer case, I think it's more conceptually "honest" to be consistent by sticking to a singular. But yes, as the article says, consistency is key.

The implementation of single record or for collections, base endpoint must be same, you can differentiate with passing single object id to fetch particular record, by this approach tracking of API is easy, I much appreciate your thoughts.
Thanks

So, users are using Rest API with postman or something? I thought apps uses APIs instead of user seeing these. These rules feels more like "7 Rules for Browser URL for readable navigation". For example rule 6, where there can be multitude of different kind of integrations to different environments, and hence they might need xml etc so format can be easily changed to something else on response by just adding .xml instead of .json.

You are correct, apps are most likely to use APIs, but users \ developers are building those apps. It is not a problem to use GUID for ID or something, but I think we all would agree that it is much wiser to use "/students" instead of something like "/000001" that is more understandable and more readble.

About rule #6, when using RESTful APIs you can set either Accept header (application/xml or application/json) to indicate the server in what reperesentation you would like to receive the object.

Thanks,
Guy