Graylog2/documentation

Create API reference documentation

asachs01 opened this issue · 0 comments

Context

As a user, I and other users within my org want to interact with Graylog programmatically rather than through the UI. Given that there are no API reference docs, this forces me to go through the UI to find out more about the endpoints, which feels a bit onerous at times.

Expected Content

A complete set of reference documentation that describes:

  • All endpoints
  • The expected methods I can use on those endpoints
  • Any response codes I can expect to receive from hitting the endpoints
  • The attributes and their associated types (e.g., client_id: string)

Additional info

As it stands, I've used the /api-docs endpoint to generate what I think is a complete (or near complete) listing of the routes:

https://gist.github.com/asachs01/f1f317b2924a688deb8ed2520a4520bd

I believe that would be enough to get us started on working on a set of reference docs. The "why" or "what's the business value of doing this" is:

  1. Our users and our customers have needed this for some time to enable them to interact with Graylog's API without having to go through the UI or suss out things on their own
  2. Continuing to kick this can down the road will inevitably make it a much more laborious task
  3. It's tech debt and we're only borrowing against our own time
  4. The lack of documents make it difficult to support any customers who might be using the API because there's no place that I can readily go to outside of a lab, or spinning up an instance via Docker that has this info