Using declarative APIs

1. Log in to Platform UI.

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

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

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

5. Enter the values for the required fields. For more information, see Custom resource values.

6. Click Create to initiate the deployment of your instance. You are redirected to the home page. The declarative API 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 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- the name of the configMap that contains the API document. The document can consist of compressed data in gzip, bzip2, or zip format to help avoid the 1MB limit.

     • spec.definition.external - an external endpoint containing the API definition that is fetched 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.

   • If you want this API to be created as a draft in an API manager instance, define these 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.

   • 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
       share:
         apim:
           credentialsSecret: apim-credentials
           providerOrg: main-demo

3. Apply the YAML file to the cluster:

   oc apply -f api.yaml

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

   oc get api

Create a secret containing the credentials for the API manager you want the declarative API to use.

You can have multiple secrets in the same namespace, and also have APIs 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, given that you can access another system without a dependency on engaging the user. However, if you need to use basic authentication credentials (username and password), you can do so by using the API Connect local user registry.

   • To use an API key, generate a key by following the instructions in Managing platform REST API keys in the IBM API Connect documentation. (If API manager is set up with more than one provider realm, you can use a key with the value of 'realm'.)

   • You need to configure your API key as a multi-use API key. For more information, see Configuring API key settings.

   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.

2. 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:

   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>     

3. 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, replacing <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>"
   }

4. 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, replacing <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

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