Hacker News Reader

Comment by misterbowfinger | Hacker News Reader

> 5. Avoid Non-RESTful Routes

Every "large" project gets to a point where some routes aren't totally RESTful. It happens. But it's not great advice to say that non-RESTful routes are always a code smell.

View on HN

What a total RESTful route to begin with ? I thought REST had nothing to do with "routes", url or resources but how the state of the application is communicated in an API ? It seems to me the Roy wrote something with a certain perspective, someone came up, read the paper and decided to apply his writings to something totally unrelated because he didn't like SOAP ... I personally stopped using that word so I don't have to confront and debate with "REST purists" and just went back to talking about web service, because that's what it is.

The idea is to limit exposed routes to the standard CRUD routes: create (/new), read (/show), update (/edit), delete (/destroy).

I thought the idea was to make an API behave like a webpage by using hyperlinks that represents the state of the application, so in theory a "smart" client could navigate an API autonomously like a human interacts with a web page ? Because otherwise it's no different from RPC.

I think you are thinking of HATEOAS. Read about it here: https://en.wikipedia.org/wiki/HATEOAS?wprov=sfla1

Ugh, no. The idea is to use standard HTTP verbs (GET, POST, PUT, DELETE) with noun routes, like:

    Create: POST /resources (or PUT /resources/42)  
    Read: GET /resources/42  
    Update: PUT /resources/42 (or PATCH /resources/42)  
    Delete: DELETE /resources/42
    List/Search: GET /resources

As commonly applied it means don't reinvent an RPC+identity+caching+encryption+compression mechanism on top of HTTP because HTTP/S itself is already an RPC mechanism with optional encryption + compression + caching support and URIs provide identity.

HTTP verbs are the operations you wish to perform. GET on a "/" resource is effectively a listing, GET on "/identifier" retrieves a specific item. PUT updates, POST creates new, DELETE is obvious. SOAP was a bad idea because it stuffed an extra RPC layer on top of HTTP's existing layer, requiring you to parse the body to find the content. Thus almost anything interacting with SOAP had to understand both HTTP and SOAP, plain HTTP tools were useless.

HTTP provides out-of-band signaling and extensions with headers. It also has a built-in mechanism to negotiate wire and content formats with Accept/Content-type. All of this means it automatically supports graceful degradation and backwards-compatibility. HTTP is stateless so unless you go out of your way to break that property it scales really well.

URIs identify the resource you want to perform the operation on. Items that are children are located "under" their parents: "/parent/42/childtype/child_id". Again - why introduce some extra system for describing these relationships and identifying resources when URIs already do a fine job of that?

If you want to take it even further you can use URIs in your data types. For example if a child needs to indicate its parent you can provide the parent URI (just the path/query/fragment portion) rather than a parent identifier. Why should the client care how you generate identifiers? It also means you can change them in the future (e.g. Int to String). Hide implementation details of the server from clients when possible.

well articulated and concise explanation. Thank you.

Agreed. I'm working on an API where most of the endpoints are RESTful, but there's a handful where it makes total sense to break the rules in order to make everyone's lives easier.

I agree, as REST isn't a silver bullet. I do, however, also agree with TFA that you should investigate it as a "code smell", but that should be done before you actually implement it. "Do I need to actually break from the REST pattern, or is this evidence of bad modeling?"

Avoid verbose REST all together unless your core buisness is deliverying REST API for a non-evolving purpose.

Use Cmd/Qrys from CQRS, route to a single endpoint in a restful fashion, and spend more time doing instead of writing boilerplate.

Reply on news.ycombinator.com