2

REST principles are described here:

An aspect of REST I am confused about separating REST principles and REST implementations.

For example, I know REST has the following principles:

  • Client Server Architecture
  • Statelessness
  • Cacheability
  • Layered system
  • Uniform interface
    • Resource identification in requests
    • Resource manipulation through representations
    • Self-descriptive messages
    • Hypermedia as the engine of application state (HATEOAS)

However, many HTTP implementations use URLs to describe which resource they are referring to, and use standard HTTP methods (e.g., OPTIONS, GET, PUT, POST, and DELETE), which is used in particular ways.

For example:

  • GET /books/2 is used to fetch book resource #2
  • PUT /books is used to create a book resource
  • DELETE /books/2 to delete book #2.

But is this just one implementation of REST, as I could not see this described in the original REST specification: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2

For example, can this also be considered REST:

Get book #5:

POST http://example.com/api
{
     "action": "fetch",
     "resource": "book",
     "id": "5"
}

Create a book:

POST http://example.com/api
{
     "action": "create",
     "resource": "book",
     "title": "Jack and the Beanstalk",
     "Author": "John Smith"
}

Get book #5 and Genre #10

POST http://example.com/api
[
    {
        "action": "fetch",
        "resource": "book",
        "id": "5"
    },
    {
        "action": "fetch",
        "resource": "genre",
        "id": "7"
    }
]

Note that all 5 principles are not being violated, despite the fact that I am using POST for all URLs, and I am using the request body instead of the URL to identify individual resources. Therefore, is this still technically REST?

  • 3
    You have to start separating REST as architectural style from HTTP semantics. The communication protocol won't make your application to be more or less REST. It will make your application to be "more" or "less" suitable for the WWW. That's it. The more you adhere to the HTTP semantics the more advantages you take from the WWW architecture. – Laiv Dec 10 '18 at 8:34
  • But do I have to follow HTTP semantics in order to be RESTful. Note that POST is also usually used for misc tasks as well when no other HTTP verb fits e.g. multiple commands or logging in. Also I'm discussing the theoretical point of view. Not the benefits in practical situations. – Yahya Uddin Dec 10 '18 at 8:39
  • 1
    do I have to follow HTTP semantics in order to be RESTful it will depend on how these "POST" requests deal with the 5 constraints. For example, POST requests might not get along with "cacheability" or the "uniform interface". If at some point your requests barely respect the 5 constraints, it's likely you don't need a "representational state transfer" architecture. – Laiv Dec 10 '18 at 8:53
2

When talking about a RESTful web service, you need to segregate three orthogonal concerns:

  1. "RESTfulness", i.e. whether or not the architecture of the service satisfies the constraints laid out in Fielding's Thesis (you seem to have a good grasp of this).
  2. The Web, i.e. whether your service conforms to and fully uses the semantics of HTTP (this is what you are confused about; a service can be RESTful but violate HTTP). There is nothing inherently non-RESTful about building a web service entirely on POST, but it is not "webful", i.e. it does not use the semantics of HTTP and the infrastructure of the web to its full potential. Using PUT for operations that are idempotent means that the client (and any proxy server in between(!!!)) knows for a fact that it can retry the operation without consequence. Using GET for side-effect free operations means that the client (and any proxy server in between) knows for a fact that it can cache and/or speculatively prefetch the resource without consequence.
  3. URI design, i.e. what your URIs look like. For a RESTful web service, it should not matter what your URIs look like, since HATEOAS says that we are just following links that are sent to us by the server, we never actually look at those links. In other words: if you are wondering whether your URIs are "RESTful", then your service is likely not. However, there are other reasons than "RESTfulness" to care about what your URIs look like. For example, hackability (being able to simply change the URI to get the result you want), SEO, information leakage (keeping sensitive data out of URIs), or even just "beauty".
1

You refer to the Fielding thesis as a 'specification' here and in your other related question which I don't think is a proper description. The thesis lays out a number of principles which you are clearly familiar with that help us to understand how well a given architecture fits into the REST model. You might want to take some time (re)reviewing section 6 which talks about URIs and HTTP and how they relate to these principles. In particular section 6.2.5 REST Mismatches in URI and section 6.3.4 REST Mismatches in HTTP may be informative as they point to how the principles of REST is independent of these specifications.

So the short answer here is that, yes, you can define your own set of protocols and standards and make them align with REST. The problem with doing this, however, is that in order for this to be useful, you need adoption of these standards. Just implementing a REST-style approach on top of POST will yield almost no benefits. Specifically, the value of a uniform interface depends on it's adoption. When you define a new one, by definition, no one else can have adopted it. It's technically possible (though highly unlikely) that you might get people to adopt it some time in the future but that doesn't do much for you now.

Instead what you have is a new approach that tunnels over HTTP. And as Laiv points to in his comment, using POST for everything goes against the grain of the WWW infrastructure. It's also one of the fundamentals flaw that lead to the decline of WSDL/SOAP as the dominant web service standard. The other main one being the lack of a meaningful uniform interface.

0

is this still technically REST?

This isn't, to my mind, a useful framing of the question; by which I mean it isn't a question you would ask if you weren't confused.

That confusion isn't your fault - Fielding wasn't writing for a general audience.

My dissertation is written to a certain audience: experts in the fields of software engineering and network protocol design.

There's a lot, and by this I mean a whole lot, of literature written by the general audience, which adds considerably to the confusion.

An aspect of REST I am confused about separating REST principles and REST implementations.

There's only one implementation of REST that has significant mind share: the World Wide Web. Fielding (5.1.5)

The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction.

It might also be useful to review Fielding 6.5.2

What makes HTTP significantly different from RPC is that the requests are directed to resources using a generic interface with standard semantics that can be interpreted by intermediaries almost as well as by the machines that originate services. The result is an application that allows for layers of transformation and indirection that are independent of the information origin, which is very useful for an Internet-scale, multi-organization, anarchically scalable information system.

(emphasis added).

I'd also encourage you to look at Richardson's 2008 talk, Justice Will Take Us Millions of Intricate Moves.

The Internet is not a truck. When people in the 90s said "WWW" instead of "HTTP" they were on to something. HTTP is only one of the Web technologies, and it's not the most important one.

What the Web had going for it was two other technologies that had never been seen before. There was an addressing technology, the URI, which killed off the other Internet protocols.

And there was a hypertext markup language, HTML, which made it possible to put something entirely new on the Internet without inventing a new protocol.

3

An aspect of REST I am confused about separating REST principles and REST implementations.

Probably 99% of people are confused. People can read about REST but when it comes to implementation, it's hard to find a good RESTful example implementation. One of the reason is everyone calls their APIs REST API when what they really mean is HTTP API.

Actually, there's a reference implementation as mentioned by Roy, REST was what guided them in building the HTTP. So, you should really look and understand it. It's not as simple as understanding that to fetch you should use GET and to create you should use POST. What's more important is that GET requests are cacheable and if you want to have RESTful API implementation that it should be cacheable, otherwise that API won't be suitable to be used on the Web.

How GET /books/2 is used to fetch book resource #2 is not really the point (how the URLs should be formed), the point is you want that opaque identifier to be cacheable after someone fetch it. Can it be cached if the detail of the request is in the body? How long should it be cached? What happens if someone updates it?

Another thing that makes it hard to see what REST is because it's an architecture style. It's not an architecture, different architectures can have REST style. I find this Roy's REST in AEM presentation is helpful in interpreting what REST is.

  • 2
    One of the reason is everyone calls their APIs REST API when what they really mean is HTTP API -- Or "JSON endpoint." Increasingly I am finding that REST is a red herring. What people actually need is an endpoint that embodies business operations, not more CRUD. – Robert Harvey Dec 11 '18 at 18:28
3

Assuming you have a standardized and well defined semantic for each actions, and that the actions aren't extensible by users of the protocol, and assuming the protocols semantics are such that you can build layered components that understands these semantics, and that you can build a generic client that can be repurposed to suit any applications without protocol changes, then yes, it is possible they may be REST in principle, but not HTTP REST.

However, the API you described isn't making a clear distinction between REST metadata (e.g. resources identifier) to actual data. An improved version that makes this distinction obvious (and more compliant of "Uniform Interface") might be:

POST http://example.com/api
{ 
  "action": "fetch", 
  "resource": {"name": "book", "id": "5"}
}

POST http://example.com/api 
{ 
  "action": "create", 
  "resource": {"name": "book", "id": "5"},
  "title": "Jack and the Beanstalk", 
  "Author": "John Smith" 
}

In this REST system, the uniform interface is a dictionary instead of a URI string. Just like HATEOAS URI, these Dictionary-URI should be treated as opaque identifier of any resources within the system. I would consider a Dictionary-URI to be over complicating the identity system, but in principle it does not necessarily violate REST.

Note that neither this example nor your original example demonstrates HATEOAS properly, which runs much deeper into the architectural style than most people realise.

If you build your architecture following REST, then yes, it's possible to make a REST API that have the same properties as HTTP, without using any HTTP features. However, you really should consider why you'd ever want to do this, because one of the benefit of HTTP REST is that standardization allows you to benefit from reusing existing standardized components.

-1

To understand REST I think you have to understand the alternatives.

For example, look at ebXML

http://docs.oasis-open.org/ebcore/ebcore-au/v1.0/ebcore-au-v1.0.html

That's just one document about agreeing an update. and it has 10 times the detail of Fieldings dissertation.

The popularity of REST comes not from the rigour of its specification, or clever architecture principles but the common sense of saying

"Hey, why don't we just send simple messages over HTTP like we do with our website?"

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.