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?
Aucun commentaire:
Enregistrer un commentaire