[EPIC] Provide API migration guide content

[tmetzke]

Acceptance criteria

• An overview of changes users will face when moving from V1 component REST APIs to the V2 C8 REST API.
• A list of general changes (like general path, naming, and request/response structure).
• An endpoint-specific changeset list, outlining adjusted/removed attributes or functionality compared to V1

Resources

• Migration guide document (🔒 internal)

Breakdown

Tasks

Preview Give feedback

1. Add general path changes #23737
   component/c8-api kind/documentation +2
   
2. Add general request/response structure changes #23738
   component/c8-api kind/documentation +2
   
3. Add general naming changes #23739
   component/c8-api kind/documentation +2
   
4. Add user task endpoints' changes #23740
   8 of 8
   component/c8-api kind/documentation support +3
   
5. Add process definition endpoints' changes #23741
   0 of 2
   component/c8-api kind/documentation +2
   
6. Add process instance endpoints' changes #23742
   0 of 5
   component/c8-api kind/documentation +2
   
7. Add decision definition endpoints' changes #23743
   0 of 2
   component/c8-api kind/documentation +2
   
8. Add decision instance endpoints' changes #23744
   0 of 2
   component/c8-api kind/documentation +2
   
9. Add decision requirement endpoints' changes #23745
   0 of 3
   component/c8-api kind/documentation +2
   
10. Add flownode instance endpoints' changes #23746
    0 of 2
    component/c8-api kind/documentation +2
    
11. Add incident endpoints' changes #23747
    0 of 2
    component/c8-api kind/documentation +2
    
12. Add variable endpoints' changes #23748
    0 of 3
    component/c8-api kind/documentation +2
    
13. Create public C8 REST API guidelines #24239
    component/c8-api kind/documentation +2
    

Related issues

• Product hub: https://github.com/camunda/product-hub/issues/2524

[tmetzke]

Alignment with DevEx team (@akeller, @christinaausley, and @pepopowitz)

• Engineering provides content in the Google Doc
• DevEx team starts with creating the appropriate structures in camunda-docs, migrates existing content
• Engineering contributes to the camunda-docs directly afterward

=> We incrementally fill the migration guide publicly to get feedback early

[pepopowitz]

Not sure this is the right place, but I'm going to stick here a few examples of API migration guides I'm finding in other places.

• Google -- I think it actually lacks a lot of context other than the first couple paragraphs, but I do appreciate the table for direct mappings.
• Primer -- not a format I'd have thought of -- sample messages, v1 next to v2. It seems like we'd have way too many changes for this to be a reasonable approach, but it is interesting.
• LaunchDarkly -- I linked directly to a section discussing a deprecated API, including some concepts/resources that entirely disappear.
• Microsoft -- this isn't an API migration guide, but I included it because it's another interesting approach -- individual pages for each change. I don't think we'd want to do this for everything, but it is an alternative to keeping all info on one page and overwhelming the user.
• Slack -- gives nice thorough context about what changed and clear instructions on how to handle the changes. Also tabular mappings which I have made obvious that I quite like.

I'll add more as I find them. I also have a couple posts out in public Slack communities to gather examples from people, and I'll share them back here.

[christinaausley]

@tmetzke I've added your drafted content into this PR -- anyone can jump into this branch and make changes.

Note that I still plan to link to the guide in a handful of docs and incorporate some tabs/restructuring for clean reading once the content is closer to complete.

[akeller]

@christinaausley @tmetzke see my comment here, regarding specific use cases for zbctl identified by the Support team.

This could warrant a separate guide entirely, transitioning from zbctl to the REST API. Can you please evaluate these use cases against your in-flight work and determine how you want to handle this feedback?

[tmetzke]

@akeller, I've added a comment to the parent issue regarding zbctl. Having a dedicated migration guide or section makes sense. I consider it out of the scope of this issue. Let's create a dedicated issue for that. It can still go into the API migration guide but has its own scope.