How to properly setup documentation for Restful services in a micro-service architecture (HAL, ALPS)

Question

I have been reading a lot about how to setup Microservices properly and I have been getting hung up with some of the more recent concepts including: HAL, ALPS, and the HAL Browser. I have historically documented things leveraging Swagger UI, however, I am coming to understand that URL centric isn't the proper way and I should be organizing documentation around resources and links which is what the newer technologies are for. I have quite a few knowledge gaps around these newer concepts, so I wanted to get a proper understanding of how these technologies work together so as I learn about each I can fit them into the puzzle.

My current understanding is:

HAL - Is an additional format on top of JSON that will let you navigate through your API via links.

ALPS - It is an additional format on top of JSON that can let me provide English based descriptions to help describe my resources

HAL Browser - Swagger UI replacement for Resource and Link centric documentation. Works with both HAL and ALPS together?

Would my current understanding of these technologies be accurate or lacking in some areas? Also implementation wise I am not fully understanding how the ALPS and HAL are interacting together. I was aware of a hal+json format and a alps+json format, but I haven't seen a hal+alps+json format.

The last area I would like to clear up is how I should be exposing these resources. Typically I always had a focus on very lean json messages is sending the hal+json format around the expected or should I be hosting those endpoints at another URL specifically for documentation similar to swagger / HAL browser?

Answer 1

Buddy! its hell of info you are trying to perceive here. Let me try to explain in steps.

Documentation centric means transitions between services and Yes, it should be called as semantically sharing information (or understanding as data types) on the web.

Step:1 Protocols (http) used for services with data types metadata and standard data types could be any form of hypermedia i.e. HTML, XML, JSON, HAL etc. For example JSON shown below, which is a root document with links. Both 'todos' and 'profile' are just hypermedia links which is HAL based and HAL only augments your current APIs.

{ "_links" : {
    "todos" : {
      "href" : "http://localhost:8080/todos"
    },
    "profile" : {
      "href" : "http://localhost:8080/alps"
    }
  }
}

Note that its just links with possible resource linking that can point to semantics of resources. HAL main focus is just linking resources/templates either by links, properties and/or embedding. Affordances explained above are mainly links shared data types at protocol level.

Step:2 ALPS are the Application level affordances which mean in above JSON i know what the Todo is but how to interact with it? To Interact with Todo, need to have Application level state transitions. Consider below the 'todo' JSON which navigated from link and shows detailed extra keywords such as 'descriptors' and 'Type' (SEMANTIC, SAFE, UNSAFE, etc).

'id' properties becomes representation identifiers. These are set or Rules to apply independent ALPS state and transitions.

{ "version" : "1.0",
  "descriptors" : [ {
    "id" : "todo-representation",
    "descriptors" : [ {
      "name" : "description",
      "doc" : {
        "value" : "Details about the TODO item",
        "format" : "TEXT"
      },
      "type" : "SEMANTIC"
    }, {
      "name" : "title",
      "doc" : {
        "value" : "Title for the TODO item",
        "format" : "TEXT"
      },
      "type" : "SEMANTIC"
    }, {
      "name" : "id",
      "type" : "SEMANTIC"
    } ]
  }, {
    "id" : "get-todos",
    "name" : "todos",
    "type" : "SAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "create-todos",
    "name" : "todos",
    "type" : "UNSAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "delete-todo",
    "name" : "todo",
    "type" : "IDEMPOTENT",
    "rt" : "#todo-representation"
  }, {
    "id" : "patch-todo",
    "name" : "todo",
    "type" : "UNSAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "get-todo",
    "name" : "todo",
    "type" : "SAFE",
    "rt" : "#todo-representation"
  } ]
}

Some links are worth to check in detail slides about ALPS and Rest Example. Hope this helped you in understanding.