REST results should be discoverable

[mpdehaan]

A big thing to REST API proponents is discoverability. In addition to having the API index like

/api

{
    'characters':  '/dev/api/characters', 
    'scenes' : '/dev/api/scenes',
    'jokes' : '/dev/api/jokes'
}

when you get back a /dev/collection result, we should fill in the objects with the URLs to their resources:

{ id: UUID, name: "roger", occupation: "shrubber",  _href: "/dev/characters/UUID" }

This means when you pass around the object you don't have to construct the URL to the object programatically, which is important because the URL of an object may change in the application, and then the code that calls it (the client) doesn't have to hunt through the application code to make updates.

The general rule of developing REST client applications is you don't build any client URLs, you first fetch /api and then look up the URLs to the collections by name, and so on.

This makes it super easy for someone to build a client app talking to the API because they can kind of surf around and discover what the API structure looks like, without having to ask backend devs.

[penberg]

Related to #25

[penberg]

We now have OpenAPI support to show endpoint paths. To make the results discoverable, we first need an API for developers to describe the endpoint results, and then make them appear in the generated OpenAPI specification.

[mpdehaan]

I think I reopened the other one and I see this is still open, so I'm going to fix my activity on the other ticket, sorry for confusion.

Did want to clarify that we still want the REST routes to appear at "/dev" in a user friendly way like the above