Launch Your First API
This tutorial describes launching and validating a simple API on API7 Enterprise. You will complete the following steps:
- Create a Published Service with a Route and an Upstream that points to
httpbin
upstream. - Validate the created API by sending a request.
Prerequisites
- Install API7 Enterprise.
- Deploy a gateway instance based on your environment:
- To deploy API7 Gateways on Kubernetes and use an ingress controller, complete Deploy Gateway and Ingress Controller on Kubernetes.
- To deploy API7 Gateways in Docker, follow the Docker instruction in Add a Gateway Instance.
Create Service and Route
- Dashboard
- ADC
- Ingress Controller
Create a Service
- Select Published Services under your gateway group from the side navigation bar and then click Add Service.
- Select Add Manually.
- From the Add Service dialog box, do the following:
- In the Name field, enter
httpbin
. - In the Service Type field, choose
HTTP (Layer 7 Proxy)
. - In the Upstream Scheme field, choose
HTTP
. - In the How to find the upstream field, choose
Use Nodes
. - Click Add Node.
- From the Add Node dialog box, do the following:
- In the Host field, enter
httpbin.org
. - In the Port field, enter
80
. - In the Weight field, enter
100
.
- In the Host field, enter
- In the Name field, enter
- Click Add. This will create a new service in the 'No Version' state.
Create a Route
- Click the service that you just created in the previous step, and then click Add Route.
- From the Add Route dialog box, do the following:
- In the Name field, enter
get-ip
. - In the Path field, enter
/ip
. - In the Methods field, choose
GET
. - Click Add.
- In the Name field, enter
Below is an interactive demo that provides a hands-on introduction to creating no-version services. You will better understand how to use it in API7 Enterprise by clicking and following the steps.
Create the following configuration file:
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
Synchronize the configuration to API7 Enterprise:
adc sync -f adc.yaml
It is recommended to use the Gateway API over the Ingress resource when working with API7 Ingress Controller, for more flexibility and extensibility.
To forward the request to httpbin.org
, create a manifest file for a route (that also creates a service):
- Gateway API
- Ingress
- APISIX CRD
apiVersion: v1
kind: Service
metadata:
namespace: api7
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: api7
name: getting-started-ip
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /ip
backendRefs:
- name: httpbin-external-domain
port: 80
apiVersion: v1
kind: Service
metadata:
namespace: api7
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
namespace: api7
name: getting-started-ip
spec:
ingressClassName: apisix
rules:
- http:
paths:
- path: /ip
pathType: Exact
backend:
service:
name: httpbin-external-domain
port:
number: 80
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: api7
name: httpbin-external-domain
spec:
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: api7
name: getting-started-ip
spec:
ingressClassName: apisix
http:
- name: getting-started-ip
match:
paths:
- /ip
upstreams:
- name: httpbin-external-domain
Apply the configuration to your cluster:
kubectl apply -f httpbin-route.yaml
Validate the API
In the dashboard, you should see a new service created under the Published Services.
- Dashboard
- ADC
- Ingress Controller
Send a request to the route:
curl "http://127.0.0.1:9080/ip"
You should see the following response:
{
"origin": "127.0.0.1"
}
Send a request to the route:
curl "http://127.0.0.1:9080/ip"
You should see the following response:
{
"origin": "127.0.0.1"
}
First, expose the service port to your local machine by port forwarding:
kubectl port-forward svc/apisix-gateway 9080:80 &
The command above runs in the background and maps port 80
of the api7-ee-3-gateway-gateway
service to port 9080
on the local machine.
Send a request to the route:
curl "http://127.0.0.1:9080/ip"
You should see a response similar to the following:
{
"origin": "127.0.0.1"
}
And that’s it. You have your first API running now.
Add APIs by Importing OpenAPI
You can also add APIs by importing OpenAPI 3.0 specification. To create a Service:
- Select Published Services under your gateway group from the side navigation bar and then click Add Service.
- Select Import OpenAPI.
- From the Add Service dialog box, do the following:
- In the OpenAPI 3.0 Specification field, upload the
httpbin.yaml
file. - In the Upstream Scheme and Service Type fields, keep the default settings
HTTP
. - In the How to find the upstream field, keep the default setting
Use Nodes
. - Click Add Node.
- From the Add Node dialog box, do the following:
- In the Host field, enter
httpbin.org
. - In the Port field, enter
80
. - In the Weight field, enter
100
.
- In the Host field, enter
- Click Next.
- In the OpenAPI 3.0 Specification field, upload the
- Click Add. This will create a new service in the 'No Version' state. The basic information and labels are imported, and all paths in the openapi file are transformed to routes in the service.
Below is an interactive demo that provides a hands-on introduction to adding services by importing OpenAPI. You will better understand how to use it in API7 Enterprise by clicking and following the steps.
Additional Resources
- Getting Started
- Best Practices