[Meta] CLI V3

[thehappybug]

Tier 1

These commands should go out in the first release. For more details about these commands, check out the spec document.

Priority goes to implementing the standalone commands first that is the commands that don't deal with API Entity/Group IDs. Our goal is to first cover the cases where the CI/CD pipeline creates artifacts without storing state in the website/dashboard.

Here's an priority-sorted list of commands (only implement the variant of these commands that does not deal with APIs on the website):

• auth:login
• auth:logout
• auth:status
• api:transform
• api:validate
• sdk:generate
• portal:generate

After these commands are done, we'll tackle the state-oriented commands that is the ones where the API spec is stored in the dashboard.

• api:import
• portal:publish

Tier 2

And these which have lower priority than the ones above. Also, they have a lot more unknown (issues to be resolved) compared to the commands above:

• api:list
• api:set
• api:transform*
• api:validate*
• sdk:list
• sdk:generate*
• sdk:download
• package:publish
• package:list
• package:info
• package:update
• portal:unpublish
• portal:scaffold
• portal:serve
• issue:report

(*) This command also has a stateless version.

Tier 3

• portal:quickstart
• sdk:quickstart
• portal:add --toc
  • Help the user generate an exhaustive list of all endpoints in the spec
• portal:add --recipe
• portal:add --guide

[safeerraees]

@shayanjalil We need APIs for api:list,, api:transform with api entity id for tier 2 development.

[safeerraees]

In portal unpublish API if an API Entity Id is provided against which there is no portal published then it should return 404, but currently, it returns 204.

[sohaibtariq]

We are skipping package publishing for now since we plan to upgrade this entire module in the apimatic app

[sohaibtariq]

Updated scope of tier 2 release:

• portal:scaffold
• portal:serve
• improved logging of responses
• usage analytics

[sohaibtariq]

Leads that want to evaluate APIMatic's Docs as Code offering currently do not have a great experience. They start with a sample repository and some Documentation. This is a pretty barebones experience, i think we can improve this greatly with a small amount of effort.

Here are some improvements we can make:

1. Docs as Code Quickstart

The objective of this quickstart would be to surface features, which are important for APIMatic, but they do not get discovered by users during the onboarding process.

• apimatic portal:quickstart
  The idea is the same as the scaffold command mentioned in the doc attached above. We need to provide a way for a new user to quickly get started with the Docs as Code Portal. This process should be interactive and walk the user through the creation of a Portal build file. The walkthrough could contain the following steps (this is a non-exhaustive list):
  • API Validation (in-terminal validation output with a reference to the VS Extension )
  • SDK Customization using codegen settings
  • Build configurations (UI customization, languages etc)
  • Guided walkthrough
  • SDK Publishing

2. Add guided walkthrough to a Build file

The process of adding a guided walkthrough is pretty difficult. A new user has to manually perform a bunch of steps to make it happen. If we can add a command like apimatic portal:add-walkthrough, that automatically creates a new .md file and .js file with skeleton code and adds references to the required places.
For reference, you can think of the functionality offered by the angular CLI in the ng generate component command

3. Allow the portal to be served locally by the CLI

We previously created an apimatic portal:serve command that deploys the portal locally and allows users to see the output. This setting needs to be tested, fixed
and released.