1

Let's say I had a REST server mocked at https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/ with two endpoints, spaceballs/raspberry and spaceballs/technician. These endpoints would respond to HTTP GET requests with a body containing quotes from Spaceballs, like

curl -X GET "https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs/raspberry"
Only one man would dare give me the raspberry!

and 

curl -X GET "https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs/technician"
We got the bleeps, sweeps and the creeps!

So all that is well and good, but what if I didn't know those two endpoints, just the URL of the RESTful server? How could I ask that (in this case, mocked) server what resources it had?

d8aninja
  • 3,233
  • 4
  • 36
  • 60
  • 1
    That linked question has some bad answers :( – Qwerky Jul 08 '19 at 08:47
  • @Qwerky I agree, I think these are two different questions and answers. I have nominated for reopening. – d8aninja Jul 08 '19 at 15:05
  • There is no standard way for RESTful servers to be self-documenting... that's what docs are for. Which is exactly what the top-voted answer on the dup question target says. – Lynn Crumbling Jul 08 '19 at 19:16
  • @LynnCrumbling "Every client request and server side response is a message and, in an ideal RESTful ecosystem, these messages must be self descriptive." https://swagger.io/resources/articles/best-practices-in-api-design/ – d8aninja Jul 18 '19 at 02:56

1 Answers1

2

You shouldn't have to know those two endpoints as a client! That's one of the basic principles of REST, your resources should be discoverable.

Knowing the endpoint at https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/ your users should be able to navigate through the API using hypermedia. In practice this means that your entrypoint returns links to other related resources. Thus you should have something like this;

GET https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/

{
  "self": {
    "type": "link.list",
    "uri": "/",
    "href": "https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/"
  },
  "links": [
    {
      "rel": "film",
      "type": "link.list",
      "href": "https://https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs"
    }
  ]
}

The above response tells the client that the current URI is a list of links and there is a link (called "film") to another resource at host/spaceballs and that resource is also a list of links. Using this information the client can call that API;

GET https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs

{
  "self": {
    "type": "link.list",
    "uri": "/spaceballs",
    "href": "https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs"
  },
  "links": [
    {
      "rel": "quote",
      "type": "film.quote",
      "href": "https://https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs/raspberry"
    },
    {
      "rel": "quote",
      "type": "film.quote",
      "href": "https://https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs/technician"
    }
  ]
}

You have now used hypermedia to describe the state of your application and are on your way to writing a REST API! This is really, really important point. Descriptive links such as these are not a "nice to have" - they are required. If your API doesn't work like this it isn't REST.

Qwerky
  • 18,217
  • 6
  • 44
  • 80