juzhiyuan commented on a change in pull request #3941: URL: https://github.com/apache/apisix/pull/3941#discussion_r605710759
########## File path: docs/en/latest/getting-started.md ########## @@ -21,247 +21,264 @@ title: Getting Started # --> -## Quick Start Guide +## Getting Started -The goal of this guide is to get started with APISIX and to configure a secured public API with APISIX. -By the end of this guide, you will have a working APISIX setup and a new service which will route to a public API, which is secured by an API key. +This guide aims to get started with Apache APISIX, we will configure the service that will route to a public API, secured by an API key. -The following GET endpoint will be used for the purpose of this tutorial. This will act as an echo endpoint and will return the parameters which are sent to the API. +Also, we will take the following `echo` endpoint as an example, it will return parameters we passed. + +**Request** ```bash -$ curl --location --request GET "https://httpbin.org/get?foo1=bar1&foo2=bar2"; +$ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +``` + +**Response** + +```json +{ + "args": { + "foo1": "bar1", + "foo2": "bar2" + }, + "headers": { + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", + "Accept-Encoding": "gzip, deflate, br", + "Accept-Language": "en,zh-CN;q=0.9,zh;q=0.8", + "Cache-Control": "max-age=0", + "Host": "httpbin.org", + "Sec-Ch-Ua": "\"Google Chrome\";v=\"89\", \"Chromium\";v=\"89\", \";Not A Brand\";v=\"99\"", + "Sec-Ch-Ua-Mobile": "?0", + "Sec-Fetch-Dest": "document", + "Sec-Fetch-Mode": "navigate", + "Sec-Fetch-Site": "none", + "Sec-Fetch-User": "?1", + "Upgrade-Insecure-Requests": "1", + "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36", + "X-Amzn-Trace-Id": "Root=1-606276ab-2b451d4b36057c186d666351" + }, + "origin": "58.152.81.42", + "url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +} ``` -Let's deconstruct the above URL. -- Scheme: HTTPS -- Host/Address: httpbin.org -- Port: 443 -- URI: /get +Let's deconstruct the above Request URL. + +- Protocol: HTTP +- Port: 80 +- Host: `httpbin.org` +- URI/Path: `/get` - Query Parameters: foo1, foo2 ## Prerequisites -- This guide uses docker and docker-compose to setup APISIX. But if you have already installed APISIX in other ways, you can just skip to [step 2](getting-started.md#step-2-create-a-route-in-apisix). -- Curl: The guide uses curl command for API testing, but you can also use any other tool of your choice (Eg- Postman). +> If you have installed the Apache APISIX, feel free and skip to [Step 2](#step-2-create-a-route) please. -## Step 1: Install APISIX +- This guide uses [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) to setup Apache APISIX. +- `curl`: This guide uses the [curl](https://curl.se/docs/manpage.html) command for API testing, but you can also use any other tools, e.g [Postman](https://www.postman.com/). -APISIX is available to install in multiple operating environments. The [following document](how-to-build.md#installation-via-source-release) shows the installation steps in multiple platforms. -For the quick start let's use the docker based set up. To start the APISIX server, clone the following [repository](https://github.com/apache/apisix-docker) and navigate to the example folder and execute the following commands. +I know you're waiting for this moment for a while, let's go! -This command will start the APISIX server and the admin API will be available in 9080 port (HTTPS port: 9443). +## Step 1: Install Apache APISIX + +Thanks to Docker, we could launch the Apache APISIX and enable the [Admin API](./admin-api.md) by executing the following commands: ```bash $ git clone https://github.com/apache/apisix-docker.git $ cd apisix-docker/example $ docker-compose -p docker-apisix up -d ``` -It will take a while to download the source for the first time. But the consequent loads will be very fast. -After the docker containers have started visit the following link to check if you are getting a successful response. +It will take some time to download all needed files, and this depends on your network, please be patient. Once this step gets done, we could `curl` our Admin API to tell if the Apache APISIX launchs successfully. ```bash +# NOTE: Please curl on the machine which you run above Docker commands. $ curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' ``` -The following will be the response from the Admin API. +We expect the following data to be returned: ```json { - "node": { - "createdIndex": 6, - "modifiedIndex": 6, - "key": "/apisix/services", - "dir": true - }, - "action": "get" + "node": { + "createdIndex": 6, + "modifiedIndex": 6, + "key": "/apisix/services", + "dir": true + }, + "action": "get" } ``` -## Step 2: Create a Route in APISIX - -APISIX provides a powerful Admin API and a [dashboard](https://github.com/apache/apisix-dashboard) for configuring the routes/services/plugins. -The quickstart guide will use the Admin API for configuring the routes. +## Step 2: Create a Route -A micro-service can be configured via APISIX through the relationship between several entities such as routes, services, upstream, and plugins. -The route matches the client request and specifies how they are sent to the upstream (backend API/Service) after they reach APISIX. -Services provide an abstraction to the upstream services. Therefore, you can create a single service and reference it in multiple routes. -Check out the architecture document for more information. +Congratulations! You have a running Apache APISIX instance now! Let's create a Route next! -Technically all this information(upstream or service, plugins) can be included inside a route configuration. The route consists of three main parts. +### Before we continue -- Matching Rules: +Do you know? Apache APISIX provides the powerful [Admin API](./admin-api.md) and a [Dashboard](https://github.com/apache/apisix-dashboard) for us to use, but we will use Admin API here in this guide. Let's go! - Let's take the following scenario. - http://example.com/services/users +We could create one [Route](./architecture-design/route.md) and target it to our backend services (We call them [Upstream](./architecture-design/upstream.md) usually), when one `Request` reaches Apache APISIX, Apache APISIX will see where this Request should go. - The URL above hosts all the micro services related to the users(getUser/ GetAllUsers) in the system. For example the GetAllUsers endpoint can be reached via the following URL (http://example.com/services/users/GetAllUsers) - Now you want to expose all the `GET` endpoints(micro-services) under the `users` path. The following will be the route configuration for matching such request. +Then how does Apache APISIX know this? That's because we have a list of rules configured with Route. Here is a sample Route data: - ```json - { - "methods": ["GET"], - "host": "example.com", - "uri": "/services/users/*", - ... Additional Configurations - } - ``` - - With the above matching rule you can communicate to APISIX via the following command. - - ```bash - curl -i -X GET "http://{apisix_server.com}:{port}/services/users/getAllUsers?limit=10"; -H "Host: example.com" - ``` +```json +{ + "methods": ["GET"], + "host": "example.com", + "uri": "/services/users/*", + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } +} +``` -- Upstream information: +This Route means all inbound requests will be forwarded to the `httpbin.org:80` Upstream when they meets **ALL** these rules(matched requests): - Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to configuration rules. - Thus a single upstream configuration can comprise of multiple servers which offers the same service. Each node will comprise of a key(address/ip : port) and a value(weight of the node). - The service can be load balanced through a round robin or consistent hashing (cHash) mechanism. +- Request's HTTP method is `GET`; +- Request has `Host` Header, and its value is `example.com`; +- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`. - When configuring a route you can either set the upstream information or use service abstraction to refer the upstream information. +After this Route is created, we could use Apache APISIX's address to access our backend services(Upstream actually): -- Plugins +```bash +$ curl -i -X GET "http://{APISIX_BASE_URL}/services/users/getAll?limit=10"; -H "Host: example.com" +``` - Plugins allows you to extend the capabilities of APISIX and to implement arbitrary logic which can interface with the HTTP request/response lifecycle. - Therefore, if you want to authenticate the API then you can include the Key Auth plugin to enforce authentication for each request. +This will be forward to `http://httpbin.org:80/getAll?limit=10` by Apache APISIX. ### Create an Upstream -Execute the following command to create an upstream with the id of '50' in APISIX. Let's use the round-robin mechanism for load balancing. +After reading the above section, we know we have to set the `Upstream` for `Route`. Just executing the following command to create one: ```bash -curl "http://127.0.0.1:9080/apisix/admin/upstreams/50"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl "http://127.0.0.1:9080/apisix/admin/upstreams/50"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "type": "roundrobin", - "nodes": { - "httpbin.org:443": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } }' ``` -### Add a Route to Access the Upstream +We use `roundrobin` as our load balancer mechanism, and set `httpbin.org:80` as our Upstream target(backend server), and its ID is `50`. For more fields, please refer to [Admin API](./admin-api.md). -By default APISIX proxies the request via the HTTP protocol. As our backend is hosted in a HTTPS environment, let's use the proxy-rewrite plugin to change the scheme to HTTPS. +**NOTE:** `Create an Upstream` is not required actually, because we could use [Plugin](./architecture-design/plugin.md) to interceptor requests then response direcly, but let's assume we need to set at least one `Upstream` in this guide. + +### Bind Route with Upstream + +We just created an Upstream(Reference to our backend services), let's bind one Route with it! ```bash -curl "http://127.0.0.1:9080/apisix/admin/routes/5"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl "http://127.0.0.1:9080/apisix/admin/routes/5"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "uri": "/get", - "host": "httpbin.org", - "plugins": { - "proxy-rewrite": { - "scheme": "https" - } - }, - "upstream_id": 50 + "uri": "/get", + "host": "httpbin.org", + "upstream_id": "50" }' ``` -### Call APISIX +That's it! -Now lets call APISIX to test the newly configured route. +### Verification + +Congratulations once more! We have created one `Route` and `Upstream`, also we bind them together. Now lets call Apache APISIX to test the `created route`. Review comment: ok, just updated -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
