Rules for REST API URI Design
blog.restcase.com
Rules for REST API URI Design
1–10 of 97 posts
Re: Rules for REST API URI Design
#2is this rules are perfect?
Re: Rules for REST API URI Design
#3I would disagree on the artificial file endings. It's a very transparent way to allow the client to request a resource with a specific content type, visible right there in the URI. After all the .json and .xml are unique representations of the same resource and can reasonably have their own URI
Re: Rules for REST API URI Design
#4I think these are rather strongly written, but certainly a reasonable list. Servers should be carefully implemented to be forgiving of bad input, but always ensure perfect output.
Re: Rules for REST API URI Design
#5I love the REST principles. The RESTful ideas framework (I call it like this because I lack a better name for them) helped me organize my applications in a much more consistent manner.
I wonder if a URI like http://api.college.com/students/3248234/courses/physics/stud... would actually make sense to get a list of all the students who take the same physics course that student 3248234 takes. If yes, is there a web framework where such generic routes can be defined?
Re: Rules for REST API URI Design
#6I would disagree on the artificial file endings. It's a very transparent way to allow the client to request a resource with a specific content type, visible right there in the URI. After all the .json and .xml are unique representations of the same resource and can reasonably have their own URI
Yeah, there aren't many situations where that really washes - it's a reasonable rule to have in mind when designing your API, but it seems to clash with the principle of designing "for your clients, not your data". Your clients are often using a browser and don't get to pick the content-type they request.
I guess you could contrive to have /resources/xml/apples and resources/json/apples serve the same content, but otherwise it's query strings or interposing a 'choose a representation for your content' page.
Naturally, none of this is a problem if your clients are not humans, I suppose.
Re: Rules for REST API URI Design
#7I would disagree on the artificial file endings. It's a very transparent way to allow the client to request a resource with a specific content type, visible right there in the URI. After all the .json and .xml are unique representations of the same resource and can reasonably have their own URI
The thing is that resource should have ideally one URI and selecting representation should be done through content negotiation (e.g. Accept header). Of course having an option to use file extensions makes debugging easier in a browser.
Re: Rules for REST API URI Design
#8I would disagree on the artificial file endings. It's a very transparent way to allow the client to request a resource with a specific content type, visible right there in the URI. After all the .json and .xml are unique representations of the same resource and can reasonably have their own URI
A URI should represent a resource, regardless of its serialisation format. Serialisation really is part of the HTTP headers, and the support in there is great. Using this allows the web browser and the web server to completely negotiate an acceptable format themselves.
Adding the serialisation format to the URI also creates a conflict: what would happen if you request a .json, but the web browser doesn't accept this format ?
Re: Rules for REST API URI Design
#9Nice rules, except for #7. Class names are singular, as are most SQL tables in modern SQL. I think this pattern should be followed also in URL design, since it’s more common to refer to a single at /person/327 than the list of all people at /person.
However, everyone designing an API should be aware that the REST principles really don’t work very well without HATEOAS, and HATEOAS does not require any “designed” URLs, just that URLs be persistent. Any client to a real REST (HATEOAS) API requires exactly one URL, the root. All other URLs should be discovered by the clients by links in the resources given by the API, starting with the resource present at the root URL.
Re: Rules for REST API URI Design
#10I would disagree on the artificial file endings. It's a very transparent way to allow the client to request a resource with a specific content type, visible right there in the URI. After all the .json and .xml are unique representations of the same resource and can reasonably have their own URI
A URI should represent a resource, regardless of its serialisation format. Serialisation really is part of the HTTP headers, and the support in there is great. Using this allows the web browser and the web server to completely negotiate an acceptable format themselves. Adding the serialisation format to the URI also creates a conflict: what would happen if you request a .json, but the web browser doesn't accept this…
The last case sounds like user error to me. You could say the same for using Accept headers - what happens if the user tells their line-drawing client to request a spreadsheet?