diff --git a/en/docs/assets/img/get_started/api-overview.png b/en/docs/assets/img/get_started/api-overview.png deleted file mode 100644 index 1cddb6f823..0000000000 Binary files a/en/docs/assets/img/get_started/api-overview.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/key-gen-wizard-1.png b/en/docs/assets/img/get_started/key-gen-wizard-1.png deleted file mode 100644 index 0461f8d7e6..0000000000 Binary files a/en/docs/assets/img/get_started/key-gen-wizard-1.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/key-gen-wizard-2.png b/en/docs/assets/img/get_started/key-gen-wizard-2.png deleted file mode 100644 index 38041728eb..0000000000 Binary files a/en/docs/assets/img/get_started/key-gen-wizard-2.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/key-gen-wizard-3.png b/en/docs/assets/img/get_started/key-gen-wizard-3.png deleted file mode 100644 index dc9823282e..0000000000 Binary files a/en/docs/assets/img/get_started/key-gen-wizard-3.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/key-gen-wizard-4.png b/en/docs/assets/img/get_started/key-gen-wizard-4.png deleted file mode 100644 index 31ec951dc1..0000000000 Binary files a/en/docs/assets/img/get_started/key-gen-wizard-4.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/key-gen-wizard-5.png b/en/docs/assets/img/get_started/key-gen-wizard-5.png deleted file mode 100644 index 11d73c21c4..0000000000 Binary files a/en/docs/assets/img/get_started/key-gen-wizard-5.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/key-gen-wizard.png b/en/docs/assets/img/get_started/key-gen-wizard.png deleted file mode 100644 index 6cbc4e612b..0000000000 Binary files a/en/docs/assets/img/get_started/key-gen-wizard.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/qsg-devportal.png b/en/docs/assets/img/get_started/qsg-devportal.png deleted file mode 100644 index 053d002c4f..0000000000 Binary files a/en/docs/assets/img/get_started/qsg-devportal.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/qsg-petstore-response.png b/en/docs/assets/img/get_started/qsg-petstore-response.png deleted file mode 100644 index ae05cf7816..0000000000 Binary files a/en/docs/assets/img/get_started/qsg-petstore-response.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/qsg-publisher.png b/en/docs/assets/img/get_started/qsg-publisher.png deleted file mode 100644 index 05e2539164..0000000000 Binary files a/en/docs/assets/img/get_started/qsg-publisher.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/subscriptions-menu.png b/en/docs/assets/img/get_started/subscriptions-menu.png deleted file mode 100644 index 40148aca78..0000000000 Binary files a/en/docs/assets/img/get_started/subscriptions-menu.png and /dev/null differ diff --git a/en/docs/assets/img/get_started/test-api.png b/en/docs/assets/img/get_started/test-api.png index 95bb5bd0b5..23e14fdd64 100644 Binary files a/en/docs/assets/img/get_started/test-api.png and b/en/docs/assets/img/get_started/test-api.png differ diff --git a/en/docs/assets/img/get_started/try-out.png b/en/docs/assets/img/get_started/try-out.png new file mode 100644 index 0000000000..a0f7df19ac Binary files /dev/null and b/en/docs/assets/img/get_started/try-out.png differ diff --git a/en/docs/get-started/api-manager-quick-start-guide.md b/en/docs/get-started/api-manager-quick-start-guide.md index 818eefaa5e..54e8247f86 100644 --- a/en/docs/get-started/api-manager-quick-start-guide.md +++ b/en/docs/get-started/api-manager-quick-start-guide.md @@ -1,72 +1,74 @@ -# Quick Start Guide - API Management +# Quick Start Guide -This section is a step-by-step guide to create, publish, and invoke an API using the **WSO2 API Manager (WSO2 API-M)** Publisher and Developer Portal. +New to **WSO2 API Manager**? Not to worry, we'll guide you with the basics! -### Before you begin... - -Chose a deployment option to start WSO2 API Manager. - -=== "Docker" - - Run WSO2 API Manager using Docker +In this step-by-step guide, you’ll learn how to create, publish, and invoke an API using the Publisher and Developer Portals. - 1. Install [Docker](https://docs.docker.com/get-docker/) - 2. Pull and Start WSO2 API Manager using the following command. - - ```bash - docker run -it -p 9443:9443 -p 8243:8243 -p 8280:8280 wso2/wso2am:4.4.0 - ``` +### Before you begin... - !!! note +Choose a deployment option to start WSO2 API Manager. - - The `docker run` command will start WSO2 API Manager and expose the ports `9443`, `8243`, and `8280`. - - The default admin credentials for WSO2 API Manager are `admin/admin`. +=== "Run locally" -=== "Direct" - - Download and run WSO2 API Manager manually + Here's how you can download and run WSO2 API Manager locally: - 1. Install [Java SE Development Kit (JDK)](https://adoptium.net/temurin/releases/?arch=any&version=21) version 21 and set the `JAVA_HOME` environment variable. - For more information on setting the `JAVA_HOME` environment variable for different operating systems. + 1. Install [Java SE Development Kit (JDK)](https://adoptium.net/temurin/releases/?arch=any&version=21) version **21** and set the `JAVA_HOME` environment variable. - !!! note - - Refer to the [Setup and Install]({{base_path}}/install-and-setup/install/installing-the-product/installing-api-m-runtime/#setting-up-java_home) for a step-by-step guide on configuring Java. + !!! tip + For more information on setting the `JAVA_HOME` environment variable for different operating systems, see [Setup and Install]({{base_path}}/install-and-setup/install/installing-the-product/installing-api-m-runtime/#setting-up-java_home) - 2. Download WSO2 API-Manager + 2. Download WSO2 API-Manager. - [Open Source Distribution](https://github.com/wso2/product-apim/releases/tag/v4.4.0) - [WSO2 Official Distribution](https://wso2.com/api-manager/#) - 3. Start WSO2 API-M by navigating to the `/bin` directory using the command-line and execute the following command. - - === "Windows" + 3. Extract the downloaded zip file. + + 4. Navigate to the `/bin` folder from your command line. + + 4. To start WSO2 API Manager, execute the relevant command: + === "On MacOS/Linux" + ```bash + sh api-manager.sh ``` + + === "On Windows" + ```bash api-manager.bat --run ``` - === "Unix" - ``` - sh api-manager.sh - ``` +=== "Run on Docker" + + Here's how you can run WSO2 API Manager using Docker: + + 1. Install [Docker](https://docs.docker.com/get-docker/) if you haven't done so already. + 2. Pull and start WSO2 API Manager by executing the following command: + + ```bash + docker run -it -p 9443:9443 -p 8243:8243 -p 8280:8280 wso2/wso2am:4.4.0 + ``` + + !!! note + + - The `docker run` command will start WSO2 API Manager and expose the ports `9443`, `8243`, and `8280`. ### What you'll build -In this sample scenario, you implement a full lifecycle of an API using WSO2 API Manager. +In this sample scenario, you'll implement the full lifecycle of an API using WSO2 API Manager. -1. Creating and publishing an API via the Publisher Portal of WSO2 API-M. -2. Deploy the API in a Gateway environment. -3. Publish the API in the Developer Portal. -2. Subscribing to the API via the Developer Portal of WSO2 API-M and generating keys. -3. Invoking the API with the generated keys. +Here are the steps that we are going to follow: + +- [Step 1: Create, Deploy and Publish an API](#step-1-create-deploy-and-publish-an-api) +- [Step 2: Subscribe to the API](#step-2-subscribe-to-the-api) +- [Step 3: Invoke the API](#step-3-invoke-the-api) - Let's get started... +Let's get started... -### Step 1 - Create and publish an API +### Step 1: Create, Deploy and Publish an API -Follow the instructions below to create and publish an API via the Publisher Portal of WSO2 API-M. +Follow the instructions below to create, deploy and publish an API via the Publisher Portal of WSO2 API-M. 1. Navigate to the Publisher Portal. @@ -76,11 +78,7 @@ Follow the instructions below to create and publish an API via the Publisher Por [![Publisher portal home page]({{base_path}}/assets/img/get_started/api-publisher-home.png)]({{base_path}}/assets/img/get_started/api-publisher-home.png) -3. Create a mock REST service. - - Let's use a mock REST service to create a REST API from scratch. - - Navigate to the [Mocky.io](https://designer.mocky.io/design) website and create a mock service by providing following configurations. +3. Next, let's create a mock REST service by navigating to [Mocky.io](https://designer.mocky.io/design). You can provide the following configuration in order to create a mock service. | Field | Value | | ----------------------- |-----------------------| @@ -123,11 +121,7 @@ Follow the instructions below to create and publish an API via the Publisher Por Endpoint - https://run.mocky.io/v3 -
-

Note

-

Use the HTTP protocol because to use HTTPS you need to import the mock json server's certificate into WSO2 API-M.

-
+ https://run.mocky.io/v3/e42a76f0-95f3-4759-b658-dcc2b0c8bacd @@ -140,9 +134,9 @@ Follow the instructions below to create and publish an API via the Publisher Por -### Step 2 - Subscribe to the API +### Step 2: Subscribe to the API -Follow the instructions below to subscribe to the API and generate the keys via the Developer Portal of WSO2 API-M. +Follow the instructions below to subscribe to the API via the Developer Portal of WSO2 API-M. 1. Navigate to the Developer Portal. @@ -154,86 +148,25 @@ Follow the instructions below to subscribe to the API and generate the keys via 2. Click **Sign-In** and enter **`admin/admin`** as your credentials to sign in to the Developer Portal. -3. Click on the API thumbnail to view the overview of the API. - - [![API overview]({{base_path}}/assets/img/get_started/api-overview.png)]({{base_path}}/assets/img/get_started/api-overview.png) - -4. Register an OAuth 2.0 application. - - 1. Click **Subscriptions** on the left menu bar of the screen. - - [![Subscription Card]({{base_path}}/assets/img/get_started/subscriptions-menu.png)]({{base_path}}/assets/img/get_started/subscriptions-menu.png) - - 2. Click **SUBSCRIPTION & KEY GENERATION WIZARD** in the above screen. - - This wizard walks you through 5 steps that will register an OAuth 2.0 application which you will use to consume the `HelloWorld` API. - - [![Key generation wizard]({{base_path}}/assets/img/get_started/key-gen-wizard.png)]({{base_path}}/assets/img/get_started/key-gen-wizard.png) - - 3. Create the OAuth 2.0 application. - - Enter the application name, and click **Next** without changing any of the other default values. - - - - - - - - - - -
- Application Name - - Greetings -
Per Token Quota - 50PerMin -
- - [![Wizard - Create application]({{base_path}}/assets/img/get_started/key-gen-wizard-1.png)]({{base_path}}/assets/img/get_started/key-gen-wizard-1.png) - - 3. Subscribe the application to the API. - - This subscribes the `Greetings` application to the `HelloWorld` API on the selected Business Plan. Click **Next** without changing any of the default values. - - [![Wizard - Subscribe to new application]({{base_path}}/assets/img/get_started/key-gen-wizard-2.png)]({{base_path}}/assets/img/get_started/key-gen-wizard-2.png) - - 4. Generate the credentials for the **Greetings** OAuth2.0 application. - - The Grant Types define the various protocols, which will be allowed by the system, from which your application will be allowed to request tokens. Click **Next**. - - [![Wizard - Generate Keys]({{base_path}}/assets/img/get_started/key-gen-wizard-3.png)]({{base_path}}/assets/img/get_started/key-gen-wizard-3.png) - - 5. Generate a test access token for the **Greetings** application to access the **HelloWorld** API. - - This step allows you to specify the permissions (scopes) for the token. Click **Next** without changing any of the default values. +3. Once you click on the HelloWorld API, you will be redirected to the API overview page. Then, go ahead and click on the **TRY OUT** button. - [![Wizard - Generate Access Token]({{base_path}}/assets/img/get_started/key-gen-wizard-4.png)]({{base_path}}/assets/img/get_started/key-gen-wizard-4.png) + [![API try out]({{base_path}}/assets/img/get_started/try-out.png)]({{base_path}}/assets/img/get_started/try-out.png) - 6. Click the **copy** icon, as shown below, to copy the generated test access token to the clipboard. + And with that, we have subscribed to the API using the `DefaultApplication`. - [![Wizard - Copy Access Token]({{base_path}}/assets/img/get_started/key-gen-wizard-5.png)]({{base_path}}/assets/img/get_started/key-gen-wizard-5.png) - - 7. Click **Finish**. - - **Voila!!!** You can now test the **HelloWorld** API with the OAuth 2.0 token that you just generated. + **Voila!!!** You have now subscribed to the API and is ready for you to test out **HelloWorld** API. -### Step 3 - Invoke the API - -Follow the instructions below to invoke the previously created API with the generated keys. - -1. Click **Try Out** on the left menu bar. +### Step 3: Invoke the API - The resources of the API will be listed. +Follow the instructions below to invoke the created API. -2. Paste the access token that you previously copied in the **Access Token** field. +1. Click on **Try Out** → **API Console** from the left menu. Then, click on **GET TEST KEY** to generate a test access token. - [![Paste the access token]({{base_path}}/assets/img/get_started/test-api.png)]({{base_path}}/assets/img/get_started/test-api.png) + [![Test API]({{base_path}}/assets/img/get_started/test-api.png)]({{base_path}}/assets/img/get_started/test-api.png) -3. **If this is the first time you are using the API test console** from your browser, open a new tab and navigate to the [https://localhost:8243/](https://localhost:8243/) URL. +2. **If this is the first time you are using the API test console** from your browser, open a new tab and navigate to the [https://localhost:8243/](https://localhost:8243/) URL. This will prompt your browser to accept the certificate used by the API Gateway. This is required because by default the API Gateway uses a self-signed certificate that is not trusted by web browsers. @@ -241,11 +174,11 @@ Follow the instructions below to invoke the previously created API with the gene This certificate that is used by the API Gateway is replaced when deploying the system in production. -4. Click on the `GET` resource of the API to expand the resource and Click **Try It Out**. +3. Click on the `GET` resource of the API to expand the resource and Click **Try It Out**. [![GET resource]({{base_path}}/assets/img/get_started/expanded-get-resource.png)]({{base_path}}/assets/img/get_started/expanded-get-resource.png) -5. Click **Execute**. +4. Click **Execute**. [![GET resource]({{base_path}}/assets/img/get_started/try-api.png)]({{base_path}}/assets/img/get_started/try-api.png) @@ -253,187 +186,4 @@ Follow the instructions below to invoke the previously created API with the gene [![Successful response]({{base_path}}/assets/img/get_started/try-it-success.png)]({{base_path}}/assets/img/get_started/try-it-success.png) -__Congratulations!__ You have successfully created your first API, subscribed to it through an OAuth 2.0 application, obtained an access token for testing, and invoked your API with the access token. - -## Automate API development and deployment - -Let's look at how you can use **WSO2 API Controller (apictl)**, which is the command-line tool to move APIs, -API Products, and Applications across WSO2 API-M environments and to perform CI/CD operations. - -### Before you begin... - -Follow the instructions below to setup WSO2 API Controller. - -1. [Make sure that you run WSO2 API Manager]({{base_path}}/get-started/api-manager-quick-start-guide/#before-you-begin). - -2. Download the apictl. - - 1. Navigate to the [API Manager Tooling page](https://wso2.com/api-management/tooling/). - - 2. Download the apictl version 4.4.0 (or the latest of the 4.4.x family) based on your operating system from the **API Controller Tooling** section. - - 3. Extract the ZIP to a preferred location. - - This location will be referred to as the `apictl` directory. - - 4. Navigate to the `apictl` directory. - - !!! warning - **If you have previously used an apictl old version**, backup and remove the `/home//.wso2apictl` directory. - - 5. Optionally, execute the following command to view the available operations. - - ``` bash - ./apictl --help - ``` - -3. Point the apictl to the instance of WSO2 API-M in which you want to deploy APIs. - - Execute the following command to add an environment for this purpose. - - !!! note - - In the following command it is assumed that WSO2 API-M is run locally (localhost) using the default ports. - - For more information on adding environments using different flag combinations, see [Add an environment]({{base_path}}/install-and-setup/setup/api-controller/getting-started-with-wso2-api-controller/#add-an-environment). - - ``` bash - ./apictl add env dev \ - --apim https://localhost:9443 - ``` - - On successfully executing this command, you should see the following message. - - ``` bash - Default token endpoint 'https://localhost:9443/oauth2/token' is added as the token endpoint - Successfully added environment 'dev' - ``` - -### Step 1 - Create an API - -Follow the instructions below to create an API via WSO2 API Controller. - -1. Initialize an API project by providing a name for the project. - - First, copy the content from `https://apim.docs.wso2.com/en/4.4.0/assets/attachments/get_started/petstore.json` and create `petstore.json` file. - - Let's use the command below to create an API named `PetstoreAPI`. This creates a folder named `PetstoreAPI` in your current directory. - - ```bash - ./apictl init PetstoreAPI --oas - ``` - - On successfully executing this command, you should see the following message. - - ```bash - Initializing a new WSO2 API Manager project in /PetstoreAPI - Project initialized - Open README file to learn more - ``` - - !!! tip - - Optionally, use the following command to view the various options related to initializing a project. - - ```bash - ./apictl init --help - ``` - -2. Update the `api.yaml` file. - - 1. Open and explore the `PetstoreAPI` folder with an IDE (e.g., VSCode). - - 2. Open the `api.yaml` file. - - Alternatively, you can use a text editor to open this file as well. - - 3. Change the values of the following attributes as shown below and save the file. - - ```text - lifeCycleStatus: PUBLISHED - ``` - - ```text - production_endpoints: - url: https://petstore.swagger.io/v2 - sandbox_endpoints: - url: https://petstore.swagger.io/v2 - ``` - - !!! Note - - - Make sure that there are no spaces in-between the `context` value in the `api.yaml` file. - - Changing the default lifecycle status of the API from `CREATED` to `PUBLISHED`, will deploy the API directly to the Developer Portal and API Gateway, when you push this API to WSO2 API-M in the following step. - - If you want to push this API to the Publisher Portal only, the status should be `CREATED`. - -### Step 2 - Publish the API - -Follow the instructions below to publish an API via WSO2 API Controller. - -1. Push the API to WSO2 API-M. - - Navigate back to the `apictl` directory and execute the following command: - - !!! note - - - If you are working with a specific environment for the first time, you are prompted to enter your account credentials on WSO2 API-M. - - You can use the default admin credentials as **`admin/admin`**. - - ``` bash - ./apictl import api --file ./PetstoreAPI --environment dev - ``` - - You should now see your API deployed successfully on WSO2 API-M. - -2. Browse the Publisher and the Developer Portals to view the API details. - - - Publisher - [https://localhost:9443/publisher](https://localhost:9443/publisher) - - [![API in the Publisher]({{base_path}}/assets/img/get_started/qsg-publisher.png)]({{base_path}}/assets/img/get_started/qsg-publisher.png) - - - Developer Portals - [https://localhost:9443/devportal](https://localhost:9443/devportal) - - [![API in the Developer Portal]({{base_path}}/assets/img/get_started/qsg-devportal.png)]({{base_path}}/assets/img/get_started/qsg-devportal.png) - -### Step 3 - Invoke the API - -Follow the instructions below to invoke an API via WSO2 API Controller. - - - -1. Generate an access token using apictl. - - Navigate back to the `apictl` directory and execute the following command: - - ``` bash - ./apictl get keys -e dev -n SwaggerPetstore -v 1.0.0 -r admin - ``` - - You will get an access token that can be used to invoke your API. - - - !!! info - For more information on generating keys using apictl, see [Get keys for an API/API Product]({{base_path}}/install-and-setup/setup/api-controller/ci-cd-with-wso2-api-management/#g-get-keys-for-an-apiapi-product). - -2. Invoke the API. - - Execute the following cURL command to invoke the resource `GET /pet` of your API. - - Make sure to enter the access token that you obtained in the previous step as the `Bearer` in the request. - - ```bash - curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz....RWrACAUNSFBpxz1lRLqFlDiaVJAg" https://localhost:8243/SwaggerPetstore/1.0.0/pet/2 -k - ``` - - You will receive the following response. - - ```bash - {"id":2,"category":{"id":0,"name":"Dogs"},"name":"Crunch","photoUrls":["-"],"tags":[{"id":3,"name":"Crunchiogo"}],"status":"unavailable"} - ``` - - !!!note - Alternatively, you can consume the API as explained in the following sections using the WSO2 API-M Developer Portal. - - - [Subscribe to the API via the Developer Portal and generate keys](#subscribe) - - [Invoke the API with the generated keys](#invoke) - - [![PetStore response]({{base_path}}/assets/img/get_started/qsg-petstore-response.png)]({{base_path}}/assets/img/get_started/qsg-petstore-response.png) - +__Congratulations!__ You have successfully created, deployed and published your first API. Thereon, we've subscribed to the API and invoked it. diff --git a/en/mkdocs.yml b/en/mkdocs.yml index 17268a9ad6..457cd398dd 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -75,8 +75,7 @@ nav: - Overview: get-started/overview.md - Key Concepts: get-started/key-concepts.md - Architecture: get-started/apim-architecture.md - - Quick Start Guide: - - API Management: get-started/api-manager-quick-start-guide.md + - Quick Start Guide: get-started/api-manager-quick-start-guide.md - About this Release: get-started/about-this-release.md - Design APIs: - Design APIs Overview: design/design-api-overview.md