Part 2 - Create a Portal to publish the API Product

The second part of the guide demonstrates connecting the API Product from Part 1 to a Developer Portal User Interface.

In this guide, we’ll:

  1. Create a Portal from our API Product.
  2. Create a User with access to the Portal and API Product.
  3. Log in to the Portal UI with this user and browse the interactive API Catalog.

Prerequisites

Make sure you’ve completed part one of the Getting Started Guide before proceeding with this guide.

Create a Portal

The Portal is a resource which tells the Developer Portal how to generate and publish a static site which enables developers to interact with API Products.

Let’s create a Portal now for our Pet Store API Product:

cat <<EOF | kubectl apply -f -
apiVersion: devportal.solo.io/v1alpha1
kind: Portal
metadata:
  name: petstore-portal
  namespace: default
spec:

  # the following fields allow customizing the static content and styling
  # for this Portal.
  displayName: Petstore Portal
  description: The Developer Portal for the Petstore API
  banner:
    fetchUrl: https://i.imgur.com/EXbBN1a.jpg 
  favicon:
    fetchUrl: https://i.imgur.com/QQwlQG3.png
  primaryLogo:
    fetchUrl: https://i.imgur.com/hjgPMNP.png
  customStyling: {}
  staticPages: []

  # the Portal Web App will serve this Portal on this domain.
  domains:
  - portal.example.com

  # API Products matching these labels will be made visible on this Portal
  publishApiProducts:
    matchLabels:
      portals.devportal.solo.io/default.petstore-portal: "true"
EOF

Once the Portal has been created, we can verify that the Dev Portal has processed it by checking its status:

kubectl get portal -n default petstore-portal -oyaml
apiVersion: devportal.solo.io/v1alpha1
kind: Portal
# ...
status:
  observedGeneration: "1"
  state: Succeeded

Once the Portal is created, we can add our API Product to it. The Portal looks for API Products with the label portals.devportal.solo.io/dev-portal.petstore-portal: "true" in their custom resource. We can add that label to our API Product by running the following command:

kubectl label apiproduct petstore-product portals.devportal.solo.io/default.petstore-portal="true"

You can also create a Portal UI by using the Admin Dashboard.

The Portal UI is all set to serve up the API Product and can now be accessed via the browser. Let’s try reaching it now.

Setting up DNS for the Browser

In order to visit the Portal being served at our domain portal.example.com, we’ll need to make sure a DNS rule exists that will resolve that domain to that address.

There are many ways to set up DNS rules for the domains defined in our API Products and Portals. In production environments, you will probably want to use your Cloud Provider’s DNS solution.

For the purposes of this setup, modifying your local /etc/hosts file with an entry to manually resolve the API Product and Portal domains will be sufficient.

Let’s add entries for the api.example.com and portal.example.com domains. Make sure you’ve got the INGRESS_HOST and INGRESS_PORT environment variables set before running:

cat <<EOF | sudo tee -a /etc/hosts

# Added for the Solo.io Dev Portal Guides
${INGRESS_HOST} api.example.com
${INGRESS_HOST} portal.example.com
EOF

We should now be able to directly curl our API Product without needing to set the Host header:

curl "http://api.example.com:${INGRESS_PORT}/api/pets"

We should see the output:

[{"id":1,"name":"Dog","status":"available"},{"id":2,"name":"Cat","status":"pending"}]

Verify the Portal UI

Now that DNS is set up for our domains, we should be able to access the portal directly in the browser at http://portal.example.com:${INGRESS_PORT}. Try typing this address into your browser with the correct INGRESS_PORT:

open $(echo http://portal.example.com:${INGRESS_PORT})

Once the browser opens you should see a page that looks something like this.

Portal UI

The Portal UI is available without any authentication by default. To secure the portal you will need to create and assign users and groups to the site. More information can be found in our guide Adding Users to the Portal

Next steps

Continue on to part 3 of the Getting Started guide to see how you can customize the Developer Portal using the Admin UI.

The Getting Started guide has covered the workflow for only the most basic of use cases. More advanced features are accessible to Dev Portal users including authentication, rate limiting, canary traffic routing, and more. Please see the guides section for guides on using more advanced features of the Developer Portal.

Questions

For any questions using the Developer Portal, please visit the Solo.io slack channel at https://slack.solo.io.

If you’d like to report an issue or bug, please see the Dev Portal Issues Repository on GitHub.