API documentation is lacking key information

[pepopowitz]

The work

Note that it might be easier to accomplish some of these tasks by tackling https://github.com/camunda/developer-experience/issues/38 first.

Tasks

Preview Give feedback

1. Unify API Auth documentation #4117
   7 of 7
   component:docs epic:api-interactivity theme:api-streamline +3
   
2. Clearly describe URL schema for both self-managed and SaaS environments, across all REST APIs. #3715
   1 of 4
   component:docs theme:api-streamline +2
   
3. Update all OpenAPI specs to include a self-managed server URL and a SaaS URL option, and regenerate docs, across all REST APIs. #4654
   component:docs dx theme:api-streamline +3
   

Background

Watch @xomiamoore and @NPDeehan struggle to call the Zeebe REST API using our docs here: https://www.youtube.com/watch?v=KlWKbDkkid4&t=1h22m12s

In this case, they were specifically trying to use the Zeebe REST API, but most of the challenges they ran into apply to all our REST APIs.

Where they got stuck:

• What is the auth server URL?
  • The Authentication guide says it is for "in the cloud", but uses a localhost URL for the auth server, with no mention of the URL for SaaS.
  • We should clearly state the auth server URL for SaaS in these Authentication guides.
  • It does appear that the Modeler Auth docs do give the SaaS authentication URL, which is where they eventually found it.
• What does an example auth call look like?
  • It's present in the Authentication guide, but it takes them a while to find it. Can we highlight this more, knowing that devs are looking for something to copy/paste?
• What is the SaaS URL for the Zeebe REST API? All that's in the specifications is localhost.
  • We should state this clearly in each API's overview.
  • It would be nice to see this in the API explorer, too. We could construct a default URL better than localhost for the API explorer, with obvious placeholders for the region & cluster ID in the URL.
  • It wasn't obvious to them that they could get the URLs from the environment variables when viewing an API client. We could more prominently guide them here in the API Overview.

[pepopowitz]

cc @akeller for visibility

[akeller]

Love this! Thanks for bringing it up during the team meeting, too. Given that this is an API experience topic, consider this a 🟢 from me to be a top priority.

In this case, they were specifically trying to use the Zeebe REST API, but most of the challenges they ran into apply to all our REST APIs.

☝️ Keep relevant EMs & PMs in mind as you make changes/adjustments. If you have UI feedback for how this info may (or may not!) be presented in Console, that's good for the PM to hear, too.

[christinaausley]

I'm happy to draft up some docs adjustments 😄

[christinaausley]

FYI @pepopowitz that I'm planning to draft this up next week for your review.

[christinaausley]

Moving to Ready as @pepopowitz is on FTO 👍

[christinaausley]

@pepopowitz Is there anything I can contribute here, or should I remove myself as an assignee and just provide a review? 😄

[pepopowitz]

I've removed you @christinaausley, and I'll tag you for reviews!