REST API与Web API

Question

I am a beginner in building HTTP APIs and I seem to be confused about the difference between REST API and Web API. More I read about it on the web, confusion seems to add up. I guess Fielding has the same issue as per this link http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

I built an HTTP API at work thinking I built a REST API as everywhere I read, they were building Web/HTTP API and calling it REST.

When I found one API adhere to HATEOAS principle was the one Github REST API https://api.github.com . I tried using it for my username at Github (GET https://api.github.com/users/vvs14 ), it returned all related links as per HATEOAS principle.

It is one of the best real-world API which is close to REST specification, IMHO. Although I could not understand which URI supports what operation on it and how to find it in case of any REST API if I am a consumer of it or how to tell it to the consumer if I am hosting the API?

One good blog on it is https://www.e4developer.com/2018/02/16/hateoas-simple-explanation/ .

All other examples are given in most of the blogs just tell to use JSON to be REST API, put everything as Resource to be REST API and use HTTP verbs for CRUD operations to be REST API. I don't find any to these to be true.

At my work, I use Sendgrid's Web API to send emails to clients and they call it Web API, not REST, which I think is pretty true.

Can anyone please clear the difference between these two, with examples?

If Github API is a right example of REST API, how can we know which URI supports which operations as Media type is not mentioned here?

Answer 1

The only resource that can tell you what it supports is the resource itself. Any information a resource gives you about what other resources support is purely advisory. The only true way to find out is to try it and handle success/failure. This is because what requests are accepted might change minute-by-minute (eg delete).

If your API could be navigable and forms submittable in a web browser — a client that knows nothing about your API other than the starting URL and HTML format — and assuming text/html was a negotiable representation of your API, then it is RESTful. It can be RESTful even if it is not navigable in a browser but that's harder to demonstrate.

Answer 2

You are right, there is a lot of confusion. Experts typically refer to 'true' REST APIs as HATEOAS or hypermedia-driven API's to avoid that confusion. Most API's that do call themselves REST api's typically aren't.

So when talking with other engineers about REST apis, it's helpful to first clarify what everyone considers REST and not REST. They're not bad engineers for not knowing, the term 'REST' just kind of got a life of its own , and I would say that HATEOAS is probably a lot more of a niche skill.

I agree with Nicholas Shank's answer that in many cases that the universal thing to do figure out if for example a DELETE works, is to actually issue the DELETE and see if it worked afterwards.

This isn't always helpful though, because many people building API's will want to not show a 'delete' button if it wouldn't work anyway.

So what is a reasonable way to tell a client that DELETE is available? The HTTP standard actually does have an Allow header that you could use to find out what methods work on a given endpoint. To find out what those are, you can issue an OPTIONS request. Not every framework supports this out of the box, but it's a legitimate way to do this.

Another way to tell a client in advance is to embed this information in the resource you are accessing. A couple of examples:

1. link hints is a draft internet standard, that could give these hints in a variety of different places, such as HAL, the HTTP Link header or others. It basically suggests a universal format for this information.
2. If you use something like OpenAPI, you can add to your API specification which methods will and wont work. This can work well for cases where you know a DELETE will simply never work, but it won't help you really well in cases where different users might have different levels of access, and some people can use DELETE and others can't.
3. You can embed this information in your own format, by expressing it as a set of permissions, maybe in a JSON format that your application understands to interpret whether certain actions may be performed.
4. Some HATEAOS formats explicitly embed information about what kind of actions can be taken via actions. A great example is the SIREN format. HAL does not natively have this.

Ultimately a good HATEAOS format will not only return information about the resource and relationships to others, but also will give a set of potential actions that can be taken. Most REST APIs that are HATEAOS tend to not do this, but HTML is the best example of one that does. If there's no link, button or form to do an action, a user can't discover that action.

A link-hints example, embedded in HAL

{
  "_links": {
    "self": {
      "href": "/orders/523",
      "hints": {
        "allow": ["GET", "DELETE"],
      }
    }
  }
}

A SIREN example

 {
  "class": [ "order" ],
  "properties": { 
      "orderNumber": 523, 
  },
  "actions": [
    {
      "name": "delete-order",
      "title": "Delete Order",
      "method": "DELETE",
      "href": "/orders/523",
    }
  ],
  "links": [
    { "rel": [ "self" ], "href": "/orders/523" },
  ]
}

An OPTIONS response

HTTP/1.1 200 OK
Allow: GET, DELETE