W-13750485 APIM <> APIG by glenn-rodgers-sf · Pull Request #537 · mulesoft/docs-api-manager

glenn-rodgers-sf · 2023-09-05T14:10:58Z

Writer's Quality Checklist

Before merging your PR, did you:

Run spell checker
Run link checker to check for broken xrefs
Check for orphan files
Perform a local build and do a final visual check of your content, including checking for:
- Broken images
- Dead links
- Correct rendering of partials if they are used in your content
- Formatting issues, such as:
  - Misnumbered ordered lists (steps) or incorrectly nested unordered lists
  - Messed up tables
  - Proper indentation
  - Correct header levels
Receive final review and signoff from:
- Technical SME
- Product Manager
- Editor or peer reviewer
- Reporter, if this content is in response to a reported issue (internal or external feedback)
If applicable, verify that the software actually got released

bjoson-mulesoft · 2023-10-12T18:06:32Z

 .. Click the API from the list under **Select API**. You can search for a specific API if needed.
 .. Update the *Asset type*, *API version*, and *Asset version* if needed.
-
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. However, you must fix some conformance issues, such as applying policies, after deploying the API instance.


I don't understand what you're trying to say here. Is the non-conformant label not accurate if they haven't yet deployed the API instance? Would some instances already be deployed so that the label is accurate? Also, chose is past tense, which is against our standard. Would the following be accurate?
For deployed instances that are RAML/OAS asset type, if Conformance Status is non-conformant, view the Governance Report to view information needed to find and fix the conformance issues. See ...

I wouldn't put an example of what the conformance issue might be here, but leave that to the linked topic. Otherwise, there is unnecessary duplication and too much too soon.

bjoson-mulesoft · 2023-10-12T18:07:33Z

-
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. However, you must fix some conformance issues, such as applying policies, after deploying the API instance.
+ 
+After deploying the API, view the *Governance Report* to fix conformance issues. For more information about governing API instances, see xref:govern-api-instances.adoc[].


See previous comment. I'd combine this with the above as suggested there.

bjoson-mulesoft · 2023-10-12T18:10:58Z

 ** **HTTP API:** Select this option if you do not have an API definition file you want to include for your asset.

 .. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. However, you must fix some conformance issues, such as applying policies, after deploying the API instance.


Same comment as above. Can you just reuse the same text here?

bjoson-mulesoft · 2023-10-12T18:11:08Z

 .. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. However, you must fix some conformance issues, such as applying policies, after deploying the API instance.
+ 
+After deploying the API, view the *Governance Report* to fix conformance issues. For more information about governing API instances, see xref:govern-api-instances.adoc[].


bjoson-mulesoft · 2023-10-12T18:11:23Z

 This option is not available for Flex Gateway runtime at this time.

 .. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. However, you must fix some conformance issues, such as applying policies, after deploying the API instance.


bjoson-mulesoft · 2023-10-12T18:11:34Z

 .. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. However, you must fix some conformance issues, such as applying policies, after deploying the API instance.
+ 
+After deploying the API, view the *Governance Report* to fix conformance issues. For more information about governing API instances, see xref:govern-api-instances.adoc[].


bjoson-mulesoft · 2023-10-12T18:12:38Z

 NOTE: Anypoint API Manager supports OpenAPI Specification (OAS) 3.0, with the exception of the callback feature. To work around this issue, handle the callback outside of the Mule runtime engine domain or use an OAS 3.0 specification that does not use callbacks.

 .. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. View the *Conformance Status* of the API to ensure the API is conformant. However, you must fix some conformance issues, such as applying policies, after deploying the API instance.


I suggest editing this similarly to the prior entry. For example:

If the instance is deployed and its conformance status is non-conformant, view the governance report to view information needed to find and fix the conformance issues. See ...

I'm not sure if you need to use the bolded UI elements here, since you aren't referring to the UI, but instead speaking of it in a more conversational, general way.

bjoson-mulesoft · 2023-10-12T18:16:29Z

 .. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. View the *Conformance Status* of the API to ensure the API is conformant. However, you must fix some conformance issues, such as applying policies, after deploying the API instance.
+ 
+After deploying the API, view the *Governance Report* to fix conformance issues. For more information about governing API instances, see xref:govern-api-instances.adoc[].


Combine with the prior entry

bjoson-mulesoft · 2023-10-12T18:35:34Z

-xref:configure-multiple-credential-providers.adoc[Configure Multiple Client Providers] - You can use multiple client providers, such as OpenAM and PingFederate, to help you enforce security and regulations in your business organization. These client providers enable you to secure your operational data, including client credentials and access tokens.
+* xref:configure-multiple-credential-providers.adoc[Configure Multiple Client Providers] - You can use multiple client providers, such as OpenAM and PingFederate, to help you enforce security and regulations in your business organization. These client providers enable you to secure your operational data, including client credentials and access tokens.
+
+* xref:govern-api-instances.adoc[Govern API Instances] - You can govern API instances by using the API Governance integration with API manager. API instance governance validation report details enable you to ensure that all your API instances follow the guidelines set out by governance rulesets. 


They don't choose to use the APIG/APIM integration, so I suggest rephrasing this something like the following. I'd keep it simple here and rely on the link to the Govern API Instances page for more info.

You can govern API instances using Anypoint API Governance. View the governance validation report for governed instances to identify conformance issues and take action to fix them.

bjoson-mulesoft · 2023-10-12T19:33:48Z

+endif::[]
+
+
+API Manager is closely integrated with xref:api-governance::index.adoc[API Governance] to govern aspects of API instances with governance rulesets. Applying a governance ruleset to your API ensures that every instance of that API conforms to standards such as what policies are applied and if a TLS context is required.  


Suggested change

API Manager is closely integrated with xref:api-governance::index.adoc[API Governance] to govern aspects of API instances with governance rulesets. Applying a governance ruleset to your API ensures that every instance of that API conforms to standards such as what policies are applied and if a TLS context is required.

API Manager is closely integrated with xref:api-governance::index.adoc[Anypoint API Governance] to govern aspects of API instances with governance rulesets. Applying a governance ruleset to your API ensures that every instance of that API conforms to standards such as what policies are applied and whether a TLS context is required.

I recently learned that the only acceptable form of the product name is Anypoint API Governance. I missed this on the Product Tiering and Hierarchy sheet, and no one on our team seemed to see it either. I'm not sure how changes there are supposed to be communicated, but now they're added to Vale, so that's how I learned about it. Refs to UI as API Governance are okay where that is what it's called there, or at least that is how I'm handling it.

bjoson-mulesoft · 2023-10-12T19:50:31Z

+
+To govern an API instances, see <<apply>>.
+
+After applying a Governance ruleset to a specific API, view and fix the conformance issues for its API instances:


When used in general, governance should not be capitalized.

bjoson-mulesoft · 2023-10-12T19:50:44Z

+
+To govern an API instances, see <<apply>>.
+
+After applying a Governance ruleset to a specific API, view and fix the conformance issues for its API instances:


Suggested change

After applying a Governance ruleset to a specific API, view and fix the conformance issues for its API instances:

After applying a governance ruleset to a specific API, view and fix the conformance issues for its API instances:

bjoson-mulesoft · 2023-10-12T19:51:07Z

+* <<view-api-governance>>
+
+[[apply]]
+== Apply a Governance Rulesets


Suggested change

== Apply a Governance Rulesets

== Apply a Governance Ruleset

bjoson-mulesoft · 2023-10-12T19:55:41Z

+
+To govern API instances, you must apply a governance ruleset to your desired API. To apply a governance ruleset, see xref:api-governance::create-profiles.adoc[].
+
+Additionally, you can create custom rulesets to satisfy your specific needs. To create custom governance rulesets, see xref:api-governance::create-custom-rulesets.adoc[].


Since they will definitely need to create their own custom rulesets for governing instances if they want to really get value out of Anypoint API Governance, I suggest something a little more prescriptive, something like:
To create custom rulesets that enforce your own API management standards, see xref:api-governance::create-custom-rulesets.adoc[].

bjoson-mulesoft · 2023-10-12T20:09:00Z

+To view the conformance status of an API instance:
+
+. Navigate to *Anypoint Platform* > *API Manager*. 
+. Click the name of the API instance whose conformance status you want to view.


I'm not sure "whose" makes sense for an API, and there are precedents in the API Manager doc similar to this:
Click the name of the API instance for which you want to view the conformance status.

bjoson-mulesoft · 2023-10-12T20:12:04Z

+
+To govern an API instances, see <<apply>>.
+
+After applying a Governance ruleset to a specific API, view and fix the conformance issues for its API instances:


Suggested change

After applying a Governance ruleset to a specific API, view and fix the conformance issues for its API instances:

After applying a governance ruleset to a specific API, view and fix the conformance issues for its API instances:

bjoson-mulesoft · 2023-10-12T20:12:41Z

+
+*Instance Conformace* appears in the *API Summary* pane.
+
+. Click *Governance Report* to view the individual rules the instance breaks.


Suggested change

. Click *Governance Report* to view the individual rules the instance breaks.

. Select the *Governance Report* page to view nonconformance details for each ruleset.

It's not exactly showing the individual rule level, as it is a bit of a rollup. Unless they view the ruleset, it's not at the rule level, so at this point it is best to talk about the details for each ruleset (or you could say issues for the rulesets the instance is nonconformant to)

bjoson-mulesoft · 2023-10-12T20:13:16Z

+*Instance Conformace* appears in the *API Summary* pane.
+
+. Click *Governance Report* to view the individual rules the instance breaks.
+. Click *View details* next to each rule to learn how to fix the issue.


Suggested change

. Click *View details* next to each rule to learn how to fix the issue.

. Click *View details* for each ruleset for information on the issues.

Accessibility (next to)

Also, it is shown by ruleset, not by rule, and it doesn't really tell you how to fix the issues in most cases.

bjoson-mulesoft · 2023-10-12T20:13:56Z

+. Click *View details* next to each rule to learn how to fix the issue.
+
+[[view-api-governance]]
+== View and Fix all Instance Conformance issues in API Governance


Suggested change

== View and Fix all Instance Conformance issues in API Governance

== View and Fix all Instance Conformance Issues in API Governance

I suggest leaving out this entire section and instead just put the link to the Finding and Fixing Conformance Issues in API Instances topic in the See Also section. That section isn't just about viewing the report. It does have doc on the report, but it also tells how to dig into more levels of detail if you don't have enough information in the report.

bjoson-mulesoft · 2023-10-12T20:39:16Z

+[[view-api-governance]]
+== View and Fix all Instance Conformance issues in API Governance
+
+To view a detailed report of the conformance issues of all instances of a specific API, see xref:api-governance::fix-instance-conformance-issues.adoc[].


See the above comment

Co-authored-by: Beth Joson <88461166+bjoson-mulesoft@users.noreply.github.com>

bjoson-mulesoft · 2023-10-13T01:19:47Z

+After applying a governance ruleset to a specific API, view and fix the conformance issues for its API instances:
+
+* <<view-api-manager>>
+* <<view-api-governance>>


This link is broken now since that section is removed. The organization here is a little odd too, because you send them to <> and then have an intro and other links. You could make this bullet points instead like:
To govern an API instance:

<>

<>

For some reason the text in the <>s is invisible above, but it's the anchor names.

W-14295864 Add asset version

dhirsch1 · 2023-10-16T15:05:48Z

-.. Update the *Asset type*, *API version*, and *Asset version* if needed.
+.. Update the *Asset type*, *API version*, and *Asset version* if you are not using the latest version.
+
+For more information about versions in Exchange, see xref:exchange::asset-versions.adoc[].


Global for links to Exchange. Add ^ to indicate that the link is going outside of docs.mulesoft.com. (See the entry for External Links in the Style Guide.)

The numbering for this task is whacked in the git preview. You might want to double-check it in a local build.

All of these links link to exchange documentation on docs.mulesoft, I don't think they would still need the links?

I have tested it, and it builds correctly.

dhirsch1 · 2023-10-16T15:16:55Z

+.. Update the *Asset type*, *API version*, and *Asset version* if you are not using the latest version.
+
+For more information about versions in Exchange, see xref:exchange::asset-versions.adoc[].
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. If the *Conformance Status* is non-conformant, after deployment, view the *Governance Report* to find and fix the conformance issues. For more information about the *Governance Report*, see xref:govern-api-instances.adoc[].


This information is repeated multiple times so it is a good candidate for a partial. If you don't have time to create one now, I suggest creating a GUS story or noting it somewhere to come back to later on.

Sadly, this is the partial. The person who owned these instructions left it quite a mess. This was the best fix I could have of it at the moment.

This page is used by a lot of different pages that are all slightly different and for the most part shouldn't exist. It's hard to break the instructions into chunks smaller than this and to get them all to render correctly. Kevin and I are trying to remove some of the pages and that should make this partial more manageable.

Co-authored-by: Diane E Hirsch <diane.hirsch@mulesoft.com>

Merge pull request #536 from mulesoft/v2.x

7950af3

W-13750485 Update branch

glenn-rodgers-sf added the DO NOT MERGE UNTIL RELEASE label Sep 5, 2023

UI impacts

6224970

glenn-rodgers-sf requested a review from a team as a code owner September 28, 2023 18:40

glenn-rodgers-sf added 3 commits October 3, 2023 16:45

Edits

e494f4f

Update govern-api-instances.adoc

95aad3f

Update govern-api-instances.adoc

58c7ae9

bjoson-mulesoft reviewed Oct 12, 2023

View reviewed changes

Comment thread modules/ROOT/pages/govern-api-instances.adoc Outdated

bjoson-mulesoft reviewed Oct 12, 2023

View reviewed changes

Comment thread modules/ROOT/pages/govern-api-instances.adoc Outdated

bjoson-mulesoft reviewed Oct 12, 2023

View reviewed changes

Comment thread modules/ROOT/pages/latest-overview-concept.adoc Outdated

bjoson-mulesoft reviewed Oct 12, 2023

View reviewed changes

glenn-rodgers-sf and others added 3 commits October 12, 2023 16:38

Update modules/ROOT/pages/latest-overview-concept.adoc

aaaa255

Co-authored-by: Beth Joson <88461166+bjoson-mulesoft@users.noreply.github.com>

Update task-add-api-instance.adoc

a143b76

Update api-instance-landing-page.adoc

261b641

bjoson-mulesoft reviewed Oct 13, 2023

View reviewed changes

glenn-rodgers-sf and others added 10 commits October 13, 2023 10:29

Update govern-api-instances.adoc

0db9fac

Update govern-api-instances.adoc

1ff8b7d

Add asset version

e7b42a6

Update manage-versions-instances-concept.adoc

aeaafa3

edits

59f2793

Update manage-versions-instances-concept.adoc

414d10a

Update task-add-api-instance.adoc

ea225da

Update task-add-api-instance.adoc

fe66bc0

Merge pull request #540 from mulesoft/W-14295864-api-versioning-gr

08288f4

W-14295864 Add asset version

Update latest-overview-concept.adoc

11f60d3