Using the API Kubernetes resource

1. Log in to Platform UI.

2. On the Instances page, click Create an instance.

3. On the "Create an instance" page, click the API tile, then click Next.

4. On the "Create an API" page, enter values for the required fields. For more information, see Custom resource values.

5. (Optional) If you're not ready to deploy your instance, save a draft version of it. Click the overflow menu (three-dot icon), then click Save as draft. The configuration for the instance is stored in the Platform UI. You can continue editing the draft version until you are ready to create the instance from it.

6. Click Create to initiate the deployment of your instance. You are redirected to the home page. The API resource begins deployment and is initially in the Pending state. Click Pending to check the progress of the deployment. When the deployment completes, the status changes to Ready.

1. Log into your OpenShift cluster, using your OpenShift user credentials:

   oc login

2. Create a API YAML file. For example, you could create a file called api.yaml with the following example configuration. Update the values as indicated:

   • For metadata.namespace, enter your project (namespace) name.

   • For spec.definition, specify one of the following values (for a configMap, external, or integrationRuntime object, respectively):

     • spec.definition.configMap- A reference to the configMap that contains the API specification. The configMap data can consist of a Swagger, OpenAPI, or AsyncAPI specification in either JSON or YAML format, or it can be a compressed file in .gzip, .bzip2, or .zip format (to help avoid the 1MB limit). For more information on how to create the configMap, see "ConfigMap example" at the end of this topic.

     • spec.definition.external - an external endpoint that contains the API specification. The operator fetches this endpoint by using a REST GET call.

     • spec.definition.integrationRuntime - the REST API document that is retrieved from a running IntegrationRuntime (in the same namespace as this API). For information on how to configure the spec.definition section, see Custom resource values.

   • Set any other configuration values as required. For example:

     apiVersion: apiconnect.ibm.com/v1beta1
     kind: API
     metadata:
       name: example-api
       namespace: <namespace>
     spec:
       definition:
         configMap: example-configmap

3. Apply the YAML file to the OpenShift cluster:

   oc apply -f api.yaml

4. Confirm the status of the API resource by running the following command in the project (namespace) where you deployed it:

   oc get api

You can parameterize fields in the API specification, allowing the same API specification to be used in multiple use cases.

For example, the API specification might have a section with some parameters. This is an arbitrary example to explain the flow:

openapi: 3.0.0
x-ibm-configuration:
  gateway: datapower-api-gateway
  assembly:
    execute:
      - invoke:
          version: 2.3.0
          name: $(name)
          surname: $(surname)

The API Kubernetes resource can then have the values for the parameters, for example:

apiVersion: apiconnect.ibm.com/v1beta1
kind: API
metadata:
  name: example-api
spec:
  definition:
    configMap: example-configmap
    parameters:
      name: 'David'
      surname: 'Smith'

The end result would be that the API specification in the API Manager will have name set as David.

You can add metadata attributes to the API specification by listing them as key-value pairs in the spec section of the API resource. For example:

apiVersion: apiconnect.ibm.com/v1beta1
kind: API
metadata:
  name: example-api
spec:
  definition:
    configMap: example-configmap
    metadata:
      name: David

The end result is that the API specification in the API Manager has an additional metadata attribute of name, with a value of David.

You can optionally expose your API in an API Manager as a draft.

To create this API as a draft in an API Manager instance:

1. Create a secret that contains the credentials for the API Manager you want the API resource to use. You can have multiple secrets in the same namespace. You can have a single secret for multiple API resources and also have API resources that reference different secrets.

   1. Complete the prerequisites for authentication with an API Manager.

   Authenticating with an API Manager by using an API key is the default authentication method. This method has the benefit of being easier and more flexible, because you can access another system without a dependency on engaging the user. API keys are associated with a user account, and therefore inherit only the permissions of that user.

   Tip: If you need to use basic authentication credentials (username and password), you can do so by using the API Connect local user registry, instead of using this procedure for using an API key.

   .

    - Generate an API key by following the instructions in [Managing platform REST API keys](https://www.ibm.com/docs/en/api-connect/10.0.x?topic=applications-managing-platform-rest-api-keys) in the IBM API Connect documentation. (If the API Manager is set up with more than one provider realm, you can use a key with the value of 'realm'.)
    - Configure your API key as a multi-use API key. For more information, see [Configuring API key settings](https://www.ibm.com/docs/SSMNED_v10cd/com.ibm.apic.cmc.doc/task_cmc_apikey_onboarding.html).

   For more information on using an API key and API Connect REST APIs, see apic login and API Connect REST APIs in the API Connect documentation.

   1. Create the secret:

   cat <<EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: apim-credentials
   type: Opaque
   stringData:
     base_url: https://<api-connect-base-url>
     <credentials>
     trusted_cert: |-
       <certificate>
   EOF

   If you are using an API key, replace <credentials> with the following section, adding your own value for the api_key field:

   grant_type: api_key
   api_key: <api_key_value>

   If you are using basic authentication, replace <credentials> with the following section, adding your own values for the username and password:

     username: <username>
     password: <password>     

   1. To get the values that you need to use within the secret, run the following command in the namespace where the API Manager is installed. Replace <instance-name> with the name of the API Manager instance.

      oc get ManagementCluster <instance-name>-mgmt -o json | jq -r '.status.endpoints[] | select(.name=="platformApi")'

      This returns a JSON object with the following structure, where <api-secret-name>, and <api-connect-base-url>, are values that change depending on the name of your API Manager instance.

      {
        "name": "platformApi",
        "type": "API",
        "secretName: "<api-secret-name>",
        "uri": "<api-connect-base-url>"
      }

   2. Replace the values in the secret that you created in an earlier step, as follows:

   • <api-connect-base-url> - Use the values that were generated in the previous command.

   • <certificate> - Use the certificate content for a cert that the API Manager trusts. On OpenShift, get this content by running the following command in the namespace where the API Manager is installed. Replace <api-secret-name>, with the value that was generated in the previous step.

     oc get secret <api-secret-name> -o json | jq -r '.data["ca.crt"]' | base64 --decode

2. Define the following values in a spec.share.apim section:

   • credentialsSecret - the name created in the Create a secret with your API Manager credentials section.

   • providerOrg - the provider organization in which the draft is created. For example:

   spec:
     share:
         apim:
         credentialsSecret: apim-credentials
         providerOrg: main-demo

The following table lists the configurable parameters and default values for the custom resource.

ConfigMap example

kind: ConfigMap 
apiVersion: v1
metadata:
  name: asyncleadsapi
  namespace: cp4i
data:
  leadsStream.yaml: |
    asyncapi: 2.1.0
    info:
      description: |-
        option1

To create the configMap directly from the specification file, run the following:

oc create configmap <configmap_name> --from-file=<file_path>

For example:

oc create configmap asyncleadsapi --from-file=./leadsStream.yaml