Video_atrest-no-waves_Getting Started All
icon-play-button
wave-video-bg wave-video-bg

Installation

Installing Express Gateway is a simple 4-step process.

  1. Install Express Gateway

    npm install -g express-gateway

  2. Create an Express Gateway

    $ eg gateway create

  3. Follow the prompts and choose the Getting Started server template
     ➜ eg gateway create
     ? What is the name of your Express Gateway? my-gateway
     ? Where would you like to install your Express Gateway? my-gateway
     ? What type of Express Gateway do you want to create? (Use arrow keys)
     ❯ Getting Started with Express Gateway
       Basic (default pipeline with proxy)
    
  4. Run Express Gateway

    cd my-gateway && npm start

Untitled-4

5-minute Getting Started Guide

Before you start: Make sure you’ve installed the Express Gateway and have it up running with the Getting Started server template.

In this quick start guide, you’ll…

  1. Specify a microservice and expose as an API
  2. Define a consumer of your API
  3. Secure the API with Key Authorization

Note: Express Gateway comes with an in-memory database. All config file changes done as part of the guide will not require you to restart Express Gateway. The hot reload feature will take of this automatically without a restart.

Untitled-5
  1. Specify a microservice and expose as an API
    • Step 1
      • We’re going to specify an existing service - https://httpbin.org/ip to proxy and manage as if it were our own originating from within the firewall. The service allows users to do get a GET and returns back a JSON string as output. It’s freely available and we’re going to showcase the capabilities of the Express Gateway
      1. open another terminal window

      2. curl http://httpbin.org/ip

         {
           "origin": "73.92.47.31" # this will be your own IP address
         }
        
    • Step 2
    • sized
    • The service will be specified as a service endpoint in the default pipeline in Express Gateway. A pipeline is a set of policies. Express Gateway has a proxy policy. Using the proxy policy within the default pipeline, the gateway will now sit in front of the https://httpbin.org/ip service and route external requests to it as a service endpoint
      1. cd my-gateway/config

      2. open gateway.config.yml and find the serviceEndpoints section where a service endpoint named httpbin has been defined

         serviceEndpoints:
           httpbin:
             url: 'https://httpbin.org'
        
      3. next find the httpbin serviceEndpoint in the proxy policy of the default pipeline

         ...
           - proxy:
           - action:
               serviceEndpoint: httpbin
               changeOrigin: true
         ...
        
    • Step 3
    • sized
    • We’re going to expose the httpbin service as an API endpoint through Express Gateway. When an API is made public through an API endpoint, the API can be accessed externally.
      1. open gateway.config.yml

      2. find the apiEndpoints section where an API endpoint named "api" has been defined

        apiEndpoints:
          api:
            host: 'localhost'
            paths: '/ip'
      

    Note: the path of the API request is appended to the service endpoint by default by the proxy policy

    • Step 4
      • sized
      • Now that we have a API endpoint surfaced, we should be able to access the API through Express Gateway.
      • curl http://localhost:8080/ip
  2. Define API Consumer
    • Step 1
    • To manage our API, we’re going to define authorized users known as “Consumers” that are allowed to utilize the API.
      1. cd my-gateway

        • sized
      2. eg users create

         $ eg users create
         ? Enter username [required]: bob
         ? Enter firstname [required]: Bob
         ? Enter lastname [required]: Smith
         ? Enter email:
         ? Enter redirectUri:
         ✔ Created bob
        
  3. Secure the API with Key Authorization
    • Step 1
      • Right now the API is fully exposed and accessible via its API endpoint. We’re now going to secure it with key authorization. To do so we’ll add the key authorization policy to the default pipeline.
      • In gateway.config.yml find the pipelines section where the “default” pipeline has been defined

          pipelines:
            - name: getting-started
              apiEndpoints:
                - api
              policies:
                - key-auth:
                - proxy:
                    - action:
                        serviceEndpoint: httpbin
                        changeOrigin: true
        
    • Step 2
      • sized
      • Assign the key credential to Bob
      • eg credentials create -c bob -t key-auth -q

          $ eg credentials create -c bob -t key-auth -q
          0Er0Ldv5EHSUE364Dj9Gv:2Yzq1Pngs1JYaB2my9Ge4u
        
      • Note: the -q option above, limits the output to just the API key, making it easier for copying and pasting.
    • Step 3
      • sized
      • Curl API endpoint without credentials - FAIL

      • curl http://localhost:8080/ip

          $ curl http://localhost:8080/ip
            Forbidden
        
    • Step 4
      • sized
    • Curl API endpoint as Bob with key credentials - SUCCESS!

    • curl -H "Authorization: apiKey ${keyId}:${keySecret}" http://localhost:8080/ip

        $ curl -H "Authorization: apiKey 0Er0Ldv5EHSUE364Dj9Gv:2Yzq1Pngs1JYaB2my9Ge4u" http://localhost:8080/ip
        {
          "origin": "73.92.47.31"
        }