4 ms·

If I gave you three APIs that all claimed to be REST, could you make more than a few definitive claims on how they're to be consumed? The article calls it out,

by ctvo 6y ago

If I gave you three APIs that all claimed to be REST, could you make more than a few definitive claims on how they're to be consumed? The article calls it out, but let's take something common like what HTTP verb to use when updating a resource. Once we tackle that, maybe we'll move on to how these APIs model their sub resources. If we can't make any definitive statements and there's no specification, what does it mean to prefer REST over something else? For me, it means you enjoy arbitrary restrictions on HTTP verbs and their usage and sometimes you can maybe infer how to make a list call on a resource vs. a get call.

dwheeler 6y ago
> If I gave you three APIs that all claimed to be REST, could you make more than a few definitive claims on how they're to be consumed? The article calls it out, but let's take something common like what HTTP verb to use when updating a resource. That is a fair request. Btw let's call this RESTful for clarity. Let me attempt to put it in my own words. I (and I think many others) would expect a RESTful interface to be: - oriented around a set of resources - each resource has a unique name, typically a URL. - Resources can be either collections or individual items - there is a small fixed set of operations that can be performed on the resources, in particular, get, post, put, delete. - get returns a collection on a collection resource, and a specific item on a specific item resource. - post on a collection creates a new resource item within the collection - put or patch rewrites the item or collection - delete obviously deletes the item more collection - the server does not need to record state to order to be able to serve the request, other than perhaps just enough to do authorization and Authentication. This means that if you give me the name of a resource, I mainly know how to perform common actions upon it. Note that HATEOAS is not listed as a requirement. I think the real problem is an overloading of terms. What many people mean by a RESTful interface is what I just listed above, which is not what Fielding had in mind with the term REST. I think the term "misappropriation" is excessively harsh; Fielding does not own a trademark on the term REST. I would agree that clarity is very important, so I think it's better to use another term instead of rest when you mean something not precisely confined to Fielding's definition. I'm happy to use RESTful, but if there's a more common term that's fine. If you want to specify a RESTful interface, there is OpenAPI, which will give you that information in a formalized way.
mathw 6y ago
I would expect a few simple things - GET doesn't change anything in the server's state (nothing externally perceivable anyway), a 4xx error code means I sent something wrong, a 5xx means the server has a problem, a 2xx is some sort of success. That's about it really. Everything else is arbitrary. There'll likely be some kind of attempt to structure URIs so that resources follow some sort of scheme, but since most APIs are really RPC instead of information access this is always a nightmare.

by ctvo 6y ago

dwheeler 6y ago

> If I gave you three APIs that all claimed to be REST, could you make more than a few definitive claims on how they're to be consumed? The article calls it out, but let's take something common like what HTTP verb to use when updating a resource. That is a fair request. Btw let's call this RESTful for clarity. Let me attempt to put it in my own words. I (and I think many others) would expect a RESTful interface to be: - oriented around a set of resources - each resource has a unique name, typically a URL. - Resources can be either collections or individual items - there is a small fixed set of operations that can be performed on the resources, in particular, get, post, put, delete. - get returns a collection on a collection resource, and a specific item on a specific item resource. - post on a collection creates a new resource item within the collection - put or patch rewrites the item or collection - delete obviously deletes the item more collection - the server does not need to record state to order to be able to serve the request, other than perhaps just enough to do authorization and Authentication. This means that if you give me the name of a resource, I mainly know how to perform common actions upon it. Note that HATEOAS is not listed as a requirement. I think the real problem is an overloading of terms. What many people mean by a RESTful interface is what I just listed above, which is not what Fielding had in mind with the term REST. I think the term "misappropriation" is excessively harsh; Fielding does not own a trademark on the term REST. I would agree that clarity is very important, so I think it's better to use another term instead of rest when you mean something not precisely confined to Fielding's definition. I'm happy to use RESTful, but if there's a more common term that's fine. If you want to specify a RESTful interface, there is OpenAPI, which will give you that information in a formalized way.

mathw 6y ago

I would expect a few simple things - GET doesn't change anything in the server's state (nothing externally perceivable anyway), a 4xx error code means I sent something wrong, a 5xx means the server has a problem, a 2xx is some sort of success. That's about it really. Everything else is arbitrary. There'll likely be some kind of attempt to structure URIs so that resources follow some sort of scheme, but since most APIs are really RPC instead of information access this is always a nightmare.