Skip to content

Config API Services Portal

Jump to bottom
MCatherine edited this page Jan 5, 2023 · 7 revisions

This document introduces the steps to setup the API Services Portal to manage api access, and explains the required parameters, followed by the official documentation API Provider User Journey. For test server, follow the following steps in API Services Portal Test Server. For production, use API Services Portal Production Server

  1. Register a new namespace, follow the step here, save the client id, client secret some where

  2. Generate a Service Account, follow the step here

  3. Run this bash script configuration for Application on OpenShift Sliver Cluster
    Basic configuration of a single service and route:

    export NS="my_namespace"  // the namespace name created in step 1
export NAME="my-service" // name how you want to call your api service, could be any
echo "
services:
- name: $NAME
  host: <name>.<ocp-namespace>.svc  // name is the service name of your openshift deployment config which runs your api application, ocp-namespace is your namespace
  tags: [ ns.$NS.<env> ] // add env to the tags if have different deployment for different environment
  port: 80 // the port number of the service of your openshift deployment config which runs your api application
  protocol: http // depends on your protocal in openshift
  retries: 0
  routes:
  - name: $NAME-route
    tags: [ ns.$NS.<env> ]
    hosts:
    - $NAME.api.gov.bc.ca  // this hosts name could be any
    paths:
    - /
    methods:
    - GET
    - OPTIONS  // add this if want to avoid CORS problem
    strip_path: false
    https_redirect_status_code: 426
    path_handling: v0
" > sample.yaml

    Note: If you are running it on Windows, you can save this file as .sh and run it in the command line like this: bash my_file.sh

    This will generate a service configuration file.

  4. Add the Network Policy to the openshift namespace:

    kind: NetworkPolicy
apiVersion: networking.k8s.io/v1
metadata:
  name: allow-traffic-from-gateway-to-your-api
spec:
  podSelector:
    matchLabels:
      app: nrfc-api-test      // use app or name or whatever to match your pod label
      name: my-upstream-api  
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              environment: test
              name: 264e6f    // this is the name of the api service portal, to allow it access, we don't need to modify it
    - from:
        - namespaceSelector:
            matchLabels:
              environment: prod
              name: 264e6f

  5. Use gwa Command line to publish the api, follow the step here

    // for test server use '-T', for prod server use '-P'
gwa init -T --api-version=2 --namespace=$NS \
  --client-id=<YOUR SERVICE ACCOUNT ID> \
  --client-secret=<YOUR SERVICE ACCOUNT SECRET>

gwa pg sample.yaml

  6. To restrict access to public and ask user to apply for access

  • In API Services Portal, go to the namespace -> Products -> New Product
  • Create product given a humand readable name, and select the environment, for example select the test environment, click create
  • Click the edit button on the line under the product name, and click edit for the "test Environment Configuration" -> select authorization "Kong API Key with ACL" -> checked "Approval Required" -> click "Apply Change"
  • A plugin template will be generated. Add this plugin template to the sample.yaml file generated from previous steps, update the tags to match the tags in your sample.yaml file
  • Add the service you want to the "Active Service" image

  1. Grant the namespace access, follow the instruction here, add the "Access.Manage" permission to allow review of access request from users

  2. To publish an api service to the api directory, need two requirements. One is that the api application must connect to a dataset, the second is that need the approval from the ministry. Go to the api services portal, namespaces page, click the warning message on top of the page, will see the link to submit a ticket to request approval. Currently we need to publish the api service to the api directory in order to make it work as expected, the team is working on to see if could make the publish to api directory be optional. image

  3. To test how a real user will request an access in the preview mode, add a sample dataset to the api

  • Go to the gwa-api Swagger Console, for prod api services portal, go to here
  • Go to the put request /namespace/{ns}/datasets, try it out
  • Enter the ns name, which is the namespace you created in the api services portal
  • Update the request body, update the name, title, note to match your application, update the organization and organizationUnit to match your organization, an example as below: 
    {
  "name": "forest client",
  "license_title": "Open Government Licence - British Columbia",
  "security_class": "PUBLIC",
  "view_audience": "Public",
  "download_audience": "Public",
  "record_publish_date": "2022-01-09",
  "notes": "The Forest Client API provides users with client information from the CLIENT database.\n\n\nCLIENT is the Ministry of Forest and Range's name and address system.\n\n\nA Client is a legal entity that:\n\n-Qualifies to enter into a business relationship with the ministry\n\n-Applies to establish an account\n\n-Has been assessed a penalty under the Forest Act, or\n\n-Has an ongoing non-financial relationship with the ministry.",
  "title": "Forest Client API",
  "tags": [
    "tag1",
    "tag2"
  ],
  "organization": "ministry-of-forests",
  "organizationUnit": "timber-pricing"
}
  • Click "Execute", and this will add a sample dataset to allow a preview of the api
  • If want to delete the sample dataset, use the swagger again

  1. Link dataset to the product. Go to the api services portal, namespaces page, click the "Products", find your product created at step 6 -> click the "Edit" on the same line as the product name -> for the "Link to BC Data Catalogue" section, paste the title of the dataset you created in last step, in our example it's "Forest Client Api" -> click "update". This will link your service to the dataset and ready for preview

  2. Go to the api services portal, namespaces page, click the "Preview in Directory" under "Products", this will be the preview of how normally real users will request access to your api

  • Click on the product
  • Click "request access", enter the application name, and select the environment, click request access, and generate the secret. Save the secret somewhere. Note that this might not work in Safari, so please use Chrome or Firefox instead. Use the secret as the api key to call the api, so in the request header, put headers: {'X-API-KEY': ''}
  1. To review the access request, go to the api services portal, namespaces page, consumers section. Will see the users and requests listed, and approve or reject from there. The namespace owner who has the "Access.Mange" permission will get email notification for any access request

Notes:

  • Once have the api published through the api services portal, we don't need to route our application in openshift, so we only need the services, but don't need the webpage anymore
  • Sometimes need to rerun the network policy after a certain amount of time, or see the time out error. Make sure the pod selector label matches the service label in the corresponding openshift namespace
  • Even after deleting a namespace from the api services portal, can't use the same name again
  • For the swagger console, could get from the Portal (https://api.gov.bc.ca or https://api-gov-bc-ca.test.api.gov.bc.ca/) go to Help -> API Docs
  • To enable CORS and avoid CORS issue, add the following to your service config yaml file
plugins:
  - name: cors
    tags: [ns.$NS.<env>] 
    config:
      origins: ["*"]
      methods: [GET, POST, PUT, DELETE, PATCH]
      headers:
        [
          Connection,
          Upgrade,
          Cache-Control,
          Access-Control-Allow-Headers,
          Access-Control-Request-Headers,
          X-API-KEY, // add this if you use an api key for access management
          Keep-Alive,
        ]
      credentials: true
      max_age: 3600
  • When limit user access to our api, the api page will show "missing api key". If want to show the users the swagger console and the api options, for nestjs application with swagger, could add a route under the same service without any plugins, and move the origin plugins to the route want to protect. The root page will still be protect, so if click "try it out" in the swagger console, it will show the url to use, and protect the data by returning "missing api key"
- name: swagger-route
  tags: [ns.$NS.<env>]
  hosts:
    - $NAME.api.gov.bc.ca
  paths:
    - /api
  methods:
     - GET
  strip_path: false
  https_redirect_status_code: 426
  path_handling: v0

Forest Client API

Clone this wiki locally