I think specifications should be either really loose or really strict.

The ones that fall in the middle are harmful.

It just leads to a million kind-of-similar things but because there's insufficient similarity you can't reap the benefits of having the spec (think automated documentation tools, pluggable APIs, client/server tools, etc).

It turns into a religion and a word that everyone ends up using but hardly any two people agree on exactly what it is.

If there's a spec for something it should have a corresponding verification tool that takes your stuff as input and basically validates it down to a yes/no answer. Your API is either compliant or not end of story. It shouldn't be a shade of grey that leaves room for arguments and lengthy blog posts about the philosophy of the spec.

The spec can still accommodate and allow for some uncertainty and flexibility but in a controlled manner and while maintaining an unambiguous specification.

GraphQL will probably overtake REST in a few years time:

https://trends.google.com/trends/explore?date=today%205-y&q=...

If you were building a large scale API now, having duplicate data at each resource (eg, avatar icon URLs in /feed) or requiring users to cross reference multiple resources for a single simple task (eg GETing /users and /feed to draw a simple timeline with user avatars) is a hassle and there's no real reason to force yourself or your API consumers through it.

The GraphQL specification is here: https://facebook.github.io/graphql/

No one is stopping you from implementing a URL like: `/feed?include=users`, which is easier on the eyes than the GraphQL equivalent. But clients generally aren't aware of the `include` query or what it does unless it's advertised from the server. There's URI templates (RFC 6570) which let you advertise it as `/feed{?include}`, but few clients understand URI templates. With GraphQL, it's part of the spec, but you must know that the server follows the spec anyways.

What's the point of discoverability when consumers don't know the semantic meaning? Does it help if you discover that you can add an include query? That you can pass the value "user"? What is a user? Maybe you can look it up in Swagger. Is that still discoverable? What if it needs more than just common sense to understand the business language?

That's what a vocabulary is for. schema.org[0] has something semantically equivalent to a user, a person.

[0] http://schema.org/Person

This is exactly what PostgREST is doing, it's interface has the same expressive power as GraphQL

I think it's time to admit that REST is at best a hack as front-end devs don't want to deal with implementing RPC in the browser, even when building complex desktop replacement apps.

A formal spec will not fix the flawed notion that any/all protocol msgs can be mapped to what are essentially CRUD HTTP verbs, or that the underlying HTTP protocol was fundamentally designed for serving hypertext documents and accepting occasional form data.

A few years ago I thought that using RPC is archaic and bad design. Now with more experience I think that RPC is actually very useful for real world applications. For simple CRUD REST is wonderful, it takes effort, but you can model a lot of things with resources. But when it comes to performance and more conplex data collection it's hard to scale. Now that we have the need for batch operation we ended up with a mix of rest and roll-your-own RPC throught POST endpoint. It led me to think that maybe we should use REST only on external APIs for easy consumption and go full RPC between our services. Also JSON is so verbose for sending over the network. Oh and compressing it over HTTPS is a no-go, because of BREACH and CRIME.

> maybe we should use REST only on external APIs for easy consumption and go full RPC between our services

That implies that you have a clear distinction between external and internal APIs that doesn't change over time. Lucky you.

Formal specs[0][1][2][3] have existed for years, not necessarily from the W3C.

All of them suffer from a chicken or egg problem. Without servers following specs, there won't be clients. Without spec-based clients, servers will continue to serve ad hoc formats.

Actually it is kind of a miracle that the web was standardized around HTML and not thousands of competing markup formats. We have JSON as a defacto standard for a machine format, but it lacks semantics, which is where JSON-LD comes into play.

I have not actually seen an API using JSON-LD in the wild, but it looks promising and is a W3C recommendation. The spec says nothing about building APIs and it looks kind of ugly with all of its @ prefixes, which is where Micro API[2] comes into play.

[0] http://stateless.co/hal_specification.html

[1] http://www.hydra-cg.com/

[2] http://micro-api.org/

[3] I did not include JSON API, since it does not make hypermedia a requirement.

If you want to make REST a web API protocol from its current state of loosely gathered recommendations, why not stick to something that already exists and performs well? XML-RPC or JSON-RPC are quite good picks. Especially that you'd get plenty of almost-conforming-but-not-quite implementations for this hypothetical REST specification, which would be disastrous for the initiative in the long run.

Why the need for so much formalism with REST?

You GET or POST data, parse a response. Details are somewhat immaterial since they're mostly just values for variables. I'd definitely love to see some standard format for documentation but a world where REST nazis tell me my API lacks lazyass engineer feature X (edit: within the context of a private API) would suck.

I agree.... the API should hopefully be consistent, and this is more important still for APIs consumed by third parties, but for your internal projects - just get the damn thing to work.

Perfect REST API's are a total waste of time when building stuff for internal consumption.

I don't see the point. REST is great because it's so loosely defined. Having a standard isn't going to smooth out the quirks between REST APIs, at least not for another decade, and even so there aren't enough problems to justify adding another set of standards everyone has to read on top of all the other specs. Stop overcomplicating the web!

I guess it could help. It doesn't mean everyone is going follow it. Just look at SPDY and HTTP/2. I know server support it but most server I hit are either HTTP/1 only compliant or support parts of each protocol.

I mean REST has been successful so far so why change?

My latest project doesn't use REST.

It just talks directly to AWS Lambda functions.

What a relief.... so quick to get things done, no pointless definition and specification and no longer any need to built yet another layer of abstraction into my application.

I'm not saying there isn't a place for REST and HTTP APIs but I'm just glad that for this project I have been able to avoid all that entirely. HUGE productivity boost.

My theory on software development is that any technology that can be replaced by something more simple will eventually disappear in favor of that alternative. REST falls into that category. The future looks more like GraphQL.

Instead of a spec, I'd like a list of best practises. They would need to be sufficiently detailed that someone could verify if you are following each one.

>They would need to be sufficiently detailed that someone could verify if you are following each one.

Sounds like a spec

If they did, it would kill REST.

Maybe that would be a good thing.

Are you going to block API endpoints that don't confirm to the spec? If not, no one would bother sticking to the spec.

Doesn't apply to Ask HN, which poses open questions. Also, you invoked Tome's law: https://news.ycombinator.com/item?id=9077549