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.

Improve this question
22
  • 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, 2015 at 13:51
  • 3
    How you call it and what you call it are two different things.
    – JeffO
    Mar 23, 2015 at 14:24
  • 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, 2015 at 16:40
  • 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, 2015 at 17:36
  • 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, 2015 at 20:57

6 Answers 6

Reset to default
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.

Improve this answer
2
  • 6
    "In my experience, 90% of "REST HTTP APIs" should call themselves "just" an HTTP API." +1
    – Artur Gaspar
    Mar 23, 2015 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, 2016 at 5: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

Improve this answer
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 ?

Improve this answer
1
  • 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, 2015 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.

Improve this answer
2
  • 4
    Something RESTful would fit that definition, too.
    – Blrfl
    Mar 23, 2015 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, 2015 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).

Improve this answer
1
  • Whilst the original question was poor, this answer is solid attempt at answering the question
    – Michael Shaw
    Mar 24, 2015 at 11:00
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".

Improve this answer

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