Fix REST API - Inefficient API Description Retrieval for Markdown #3627
Description
Current Limitation
In the Publisher Portal, if the API description is saved as markdown, it is stored as a document rather than a simple text field. As a result, when Product APIs are used to fetch API metadata in both the Publisher and Developer Portals, the description field returns null.
This leads to inefficiencies because there is no direct indication that a markdown overview document exists. To retrieve the API description, the following steps are required:
- Fetch the API metadata (returns null for description if markdown is used).
- Fetch the documents associated with the API.
- Identify a document with the type name
_overviewand retrieve its content.
This requires a minimum of three API calls to obtain the API description, making the process inefficient.
Suggested Improvement
We will have to modify the REST API and solve this limitation
-
Add an Indicator for Markdown Overview:
- Introduce a flag in the API metadata indicating whether a markdown overview exists, allowing clients to fetch it selectively if needed.
-
Add a New Resource to Fetch Markdown Overview:
- Introduce a new API resource to fetch the markdown overview content by passing the API ID if the above flag is true, allowing clients to retrieve it efficiently without fetching all documents.
Version
4.4.0