Config API Services Portal

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

Register a new namespace, follow the step here, save the client id, client secret some where
Generate a Service Account, follow the step here

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

export NS="my_namespace"  // the api-gateway 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 api-gateway 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.

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

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

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"

Grant the namespace access, follow the instruction here, add the "Access.Manage" permission to allow review of access request from users
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.
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": "Access Only",
  "security_class": "HIGH-SENSITIVITY",
  "view_audience": "Government",
  "download_audience": "Government",
  "record_publish_date": "2022-01-09",
  "notes": "The Forest Client API provides users with information from the CLIENT database.\n\nCLIENT is the Ministry of Forest and Range's name and address system.\n\nClient is a legal entity that:\n\n- Qualifies to enter into a business relationship with the ministry\n- Applies to establish an account\n- Has been assessed a penalty under the Forest Act, or\n- Has an ongoing non-financial relationship with the ministry.\n\nFor further information, please visit our [wiki page](https://github.com/bcgov/nr-forest-client-api/wiki/Business-Context).\n\nBelow are the API URLs for the testing and production environments:\n\n[Testing](https://nr-forest-client-api-test.api.gov.bc.ca)\n\n[Production](https://nr-forest-client-api-prod.api.gov.bc.ca)\n\nContact Forest Digital Services for approval to access the Forests Client API before making a request. [Email us](mailto:fdsmodernizatoinprogram@gov.bc.ca) and specify the:\n- System to system connection\n- Data needed\n- Intended use\n- Users of the system consuming the information\n- Length of time access is required",
  "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

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
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': ''}

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Config API Services Portal

Notes:

Forest Client API

Clone this wiki locally