28

What would you call an API that is HTTP-based, uses URI to name resources and HTTP verbs (PUT, POST, DELETE, GET...) to manipulate those resources?

According to Roy Fielding's complaints it is not REST, because there is no hypermedia.

Internally, in my team, everyone calls it "REST API". I call it "REST-like" but it is not descriptive and its meaning is fuzzy. I'm quite confused about it, since there is huge disagreement about REST. I don't want take part in flame wars, but just use correct terms.

Martijn
  • 1,016
  • 9
  • 14
pkalinow
  • 689
  • 7
  • 13
  • http://meta.programmers.stackexchange.com/questions/6582/on-the-troubles-of-naming-and-terminology – gnat Mar 23 '15 at 12:35
  • 6
    How much of your time at work do you spend actually programming, and how much of your time do you spend deciding on what terminology to use? Suppose you release a great product but you used slightly wrong terminology in some internal documents. Would your customers care? – Brandin Mar 23 '15 at 13:51
  • 3
    How you call it and what you call it are two different things. – JeffO Mar 23 '15 at 14:24
  • 3
    You could call it API. Or HTTP API. Both are correct. It could be helpful to ask yourself why you want to be so concise on this point when natural language is quite often rather fuzzy. Is it possible you want to do this to make it clear to your co-workers that this is not REST? If so, you could consider other ways to do this more constructively. – Martijn Mar 23 '15 at 16:01
  • 16
    Does this question really warrant the snark and skepticism it's getting in the comments? It hardly seems outrageous to want a decent, widely-understood way of referring to a pretty high-level, frequently used concept. – Ben Aaronson Mar 23 '15 at 16:40
  • A tunneling API, since rest is about using HTTP features, rather than ignoring them and layering yet another ad hoc protocol over it. (or in the extreme case, tunneling a completely HTTP free protocol through the middle of it, which is sort of what SOAP was) – MatthewMartin Mar 23 '15 at 17:05
  • 7
    @Brandin, words mean things. Until I can hook a USB stick to you brain and download my code instantly, I'll have to use labels and terminology to communicate my meaning. If I say "SOAP HTTP API", that will mean something significantly different than "REST HTTP API". Naming things is a hard problem, and an important one too. – Paul Draper Mar 23 '15 at 17:36
  • @PaulDraper yet context is everything. If you have one relevant HTTP API in your team, everybody in your team will know which API you mean when you call it with any of Web API, HTTP API, REST-like API, or REST API. If you're uncomforatble with REST API being wrong, any of the others are fine. The terminology and the context combined makes them unambiguous and precise. – Martijn Mar 23 '15 at 17:43
  • @Martijn, true. The more context that already exists, the less precise your communication needs to be. – Paul Draper Mar 23 '15 at 17:46
  • I've always assumed this is the difference between `REST` and `RESTful`. The `ful` bit being linked with the `HATEOAS` element, however, it seems I may be wrong http://programmers.stackexchange.com/questions/145605/rest-vs-restful-vs-normal-web-service-the-same-or-not – Jodrell Mar 23 '15 at 17:57
  • 2
    Since it's not RESTful you could call it wakeful? – Justin Ohms Mar 23 '15 at 18:52
  • 1
    @BenAaronson: The simple fact is that "name that thing" questions are just not all that interesting. Programmers is for conceptual programming questions, not naming things so that people can find their answers elsewhere. They go against the very grain of what we do here. See [here](http://meta.programmers.stackexchange.com/q/6582/1204) for more information. The fact that this question got an interesting answer doesn't justify the other questions like this that don't get an answer because there isn't one. Use Google; that's what it's there for. – Robert Harvey Mar 23 '15 at 19:06
  • 2
    @RobertHarvey I wasn't referring to whether or not the question was on topic, more Brandin and Martijn's comments. – Ben Aaronson Mar 23 '15 at 20:14
  • 6
    Be prepared to give up on this topic with your team the next time you bring up this topic and get resistance on it. I am the type of person who finds it important that we use correct terminology so that there is less opportunity for miscommunication; many people don't think this way and will even take it as an attack on their intelligence if you try to evaluate their word/technical choices, in which case it's just not worth the argument. If you have a neurotic(or more) on your team and they are resist the notion that they aren't actually doing REST, its best just to give up on it. – Ten Bitcomb Mar 23 '15 at 20:57
  • Oh god this nonsense. I refuse to be sucked into this world of marketing buzzwords. You should too! – Lightness Races in Orbit Mar 23 '15 at 22:04
  • @JeffO: After the edition by Martijn the question has slightly changed its meaning. I have asked for a correct name. I know what I want to name - it's my API. I just doubt about the correct name for this kind of API. – pkalinow Mar 24 '15 at 08:21
  • 1
    @pkalinow: The answer to the original phrasing, *how* to call the API, is that you can call the API by making a HTTP request to the resource. That's a completely different answer than the answer you are looking for. That's why I made the edit – Martijn Mar 24 '15 at 09:42
  • @Martijn: I was not aware of such a nuance. You are right, "what" is correct, not "how". – pkalinow Mar 24 '15 at 11:51
  • @Brandin OP is probably asking this for communications with his team. Do you communicate with your team in (computer language) code? When there are >1 persons (not only programmers) working on some software, it's highly important that they have exactly same idea about how it should be. A slight miscommunication can cause reworks, bugs, delays, frustrations, hard-to-maintain code and what not. In a team, it's a must to have all on the same page about ideas of their product, your comment makes sense when you're the only programmer coding something. – 0xc0de Sep 28 '18 at 04:46
  • @0xc0de Naming things in a team is more about organization than correctness. For example we could name three parts of some source code as "component1", "component2", "component3." These names are so generic that no one could claim they are inaccurate. But they are not useful names for organizing. How about "http", "rest", and "unittest"? Now it's clearer. Maybe some of "http" is really not HTTP, though. And maybe some of "rest" is not really REST or RESTful, and maybe some of 'unittest' are not really unit tests. Such small discrepancies are OK, because these names are just for organization. – Brandin Sep 28 '18 at 05:03
  • Great question, it's sad that some "geniuses" decided to close it. – mnj Nov 22 '21 at 19:09
  • People complain that naming doesn't matter. Then sales people go off telling the customer that sure, we have a REST API. Then the customer is angry because it wasn't actually REST by any reasonable definition, and they don't like having been lied to... – Oskar Berggren Feb 01 '23 at 13:55

6 Answers6

46

Call it an HTTP API.

It conforms to HTTP standards, and doesn't have anything else layered on top (e.g. SOAP).

The HTTP standards define resources, verbs, headers, content negotiation, etc.

REST (REpresentational State Transfer) is an architecture with requirements that happen to be amenable to existing HTTP standards, but HTTP works all on its own.

In my experience, 90% of "REST HTTP APIs" should call themselves "just" an HTTP API.

Don't be ashamed to leave off the REST label. As with microservices and non-relational databases, you don't have to have a RESTful API to be cool. Roy set out to create the longest-lived, most backwards compatible, networked application architecture that he could. He did a good job. But not everything needs 40+ years of compatibility.

Robert Harvey
  • 198,589
  • 55
  • 464
  • 673
Paul Draper
  • 5,972
  • 3
  • 22
  • 37
  • 6
    "In my experience, 90% of "REST HTTP APIs" should call themselves "just" an HTTP API." +1 – Artur Gaspar Mar 23 '15 at 23:12
  • I couldn't agree more. Where I currently work, we build state-of-the art client-server UI using a cutting-edge application framework in a rapid development cycle. There's nothing RESTful about it; we only use POST. It's not trendy, but it gets the job done, and it gets it done very well. It's some of the cleanest code I've ever seen. – Robert Harvey Jun 14 '16 at 05:02
23

Richardson Maturity Models goes like this

  1. POST everywhere. A single endpoint. (SOAP)
  2. POST everywhere. Multiple endpoints. (resources)
  3. HTTP VERBS. Multiple endpoints.
  4. Like 2 and returns links to resources. (RESTful)

So according to the model I would call it a webservice conforming to richardson level 2 or something along those lines.

http://martinfowler.com/articles/richardsonMaturityModel.html

Esben Skov Pedersen
  • 5,098
  • 2
  • 21
  • 24
8

Hypermedia never really got popular with REST-like APIs - to the point that when an API actually implements hypermedia navigation, the term RESTful simply isn't enough to distinguish it from any other "RESTful" web APIs. REST has become an catch-all term or any resource-based web APIs and new names like Hypermedia API have been coined to focus on the hypermedia concept.

I don't really want to advocate the usage of incorrect terms, but I think that the general modern interpretation of REST simply means using uniform URLs and HTTP verbs for most people. It's not correct, but anyone who knows Fieldings definition, should also know that many others don't. On the other hand, anyone who knows REST only by observing how existing "RESTful" APIs are implemented, won't know what you are talking about when you mention lesser known REST constraints like HATEOAS or on-demand code. Fielding may not like it, but I think it is to late to get back to the original definition*. And let's be honest: If you hear someone talk about his REST API for the first time, you instantly assume it does not include hypermedia, don't you?

Insisting on the correct definition of RESTful usually only creates additional confusion. As with many terms that have changed their meaning over time or that the masses simply adopted wrong, I appreciate if someone knows the original definition but I wouldn't correct anyone who is using the broader modern interpretation of REST.

* and also to late to establish new terms for REST-like non-hypermedia APIs, for that matter. How should we call them anyway? ... RESTish ?

kapex
  • 309
  • 3
  • 7
  • 1
    Github's API has lots of hypermedia. I don't know how typical that is. I agree with you that the term 'RESTful' has escaped Fielding's control to embrace more things. – dcorking Mar 24 '15 at 13:31
2

It is a CRUD interface (Create, Read, Update, Delete) over HTTP.

I can't think of any authorities to back it up this assertion, so I hope you get more and better answers.

dcorking
  • 586
  • 4
  • 13
  • 4
    Something RESTful would fit that definition, too. – Blrfl Mar 23 '15 at 17:34
  • 1
    @Blrfl AFAICT Some RESTful APIS would be supersets of this. It wouldn't meet Fielding's definition if the records don't contain hyperlinks. – dcorking Mar 24 '15 at 13:29
2

You can call it whatever you like, people tend to (almost religiously) latch onto any part of the REST 'spec' that you're not following and use that as a point of protest which is highly detrimental to the development. But that said, the simple fact is that there are (nearly) zero services exist that implement true REST for their API serves.

In our team we named ours the Stateless API while it was in development because we had a legacy Stateful and Functional SOAP API that we were replacing (the legacy API itself never had an agreed and meaningful name either so we didn't get too caught up in names).

Now this project only has one API it's simply called the <project> API. When we eventually replace it, the new API will simply be known as the new <project> API.

Giving it any fancy and descriptive internal name is almost meaningless unless you have so many APIs that you need to differentiate this one from the rest (in which case you probably should rename all the others as well).

Seph
  • 129
  • 2
2

You can call it a Web API. It's a very broad term but it can avoid nitpicking about meaning of other API type definitions. The term is less technical and precise compared to alternatives like HTTP API, but that might be an advantage when talking to non-technical people.

This term is also used by Leonard Richardson (who defined the Richardson Maturity Model that is already mentioned another answer - a well accepted measurement for how close an API is to a REST architecture). It is what you get if you drop the "RESTful" part of a "RESTful Web API".

kapex
  • 309
  • 3
  • 7