Developing and Deploying APIs with Red Hat Integration

1. Create an OpenShift OAuth client for 3scale. For more details about OpenShift authentication, see OAuth Clients.

       $ oc project default
       $ cat <<-EOF | oc create -f -
       kind: OAuthClient
       apiVersion: v1
       metadata:
        name: 3scale
       secret: "<choose-a-client-secret>"
       redirectURIs:
        - "<3scale-master-domain-route>"
       grantMethod: prompt
       EOF

2. Open the 3scale Service Discovery settings file:

       $ oc project <3scale-project>
       $ oc edit configmap system

3. Configure the following settings:

       service_discovery.yml:
         production:
           enabled: true
           authentication_method: oauth
           oauth_server_type: builtin
           client_id: '3scale'
           client_secret: '<choose-a-client-secret>'

4. Ensure that users have proper permissions to view cluster projects containing discoverable services.

   For example, to give <user> view permission for the <namespace> project, use this command:

   oc adm policy add-role-to-user view <user> -n <namespace>

5. After modifying configmap, you need to redeploy the system-app and system-sidekiq pods to apply the changes.

   oc rollout latest dc/system-app
   oc rollout latest dc/system-sidekiq

1. Create an OAuth client for 3scale in Red Hat OAuth server (Keycloak).

   IMPORTANT: In the client configuration, verify that the user's username maps to `preferred_username`, so that OpenShift can link accounts.

2. Edit 3scale Service Discovery settings.

       $ oc project <3scale-project>
       $ oc edit configmap system

3. Verify that these settings are configured.

       service_discovery.yml:
         production:
           enabled: true
           authentication_method: oauth
           oauth_server_type: rh_sso
           client_id: '3scale'
           client_secret: '<choose-a-client-secret>'

4. Make sure users have proper permissions to view cluster projects containing discoverable services.

   For example, to give <user> view permission for the <namespace> project, use this command:

   oc adm policy add-role-to-user view <user> -n <namespace>

5. After modifying configmap, you need to redeploy the system-app and system-sidekiq pods to apply the changes.

Procedure

1. Click New API. A new API page opens.

2. To change the API name:

   1. Hover the cursor over the name and then click the edit icon ( ) that appears.
   2. Edit the name. For example, type Task API.
   3. Confirm the name change.

3. Optionally:

   • Add your contact information (name, email address, and URL).
   • Select a license.
   • Define tags.
   • Define a security scheme.
   • Specify security requirements.

4. Define a relative path to each individual endpoint of the API. The field name must begin with a slash (/).

   For the Task Management API example, create two paths:

   • A path for tasks: /todo

   • A path for a specific task by ID: /todo/{id}

     

5. Specify the type of any path parameters.

   For the example id parameter:

   1. In the Paths list, click /todo/{id}.

      The id parameter appears in the PATH PARAMETERS section.

   2. Click Create.
   3. For the description, type: The ID of the task to find.

   4. For the type, select integer as 32-Bit integer.

      

6. In the Data Types section, define reusable types for the API.

   1. Click Add a data type.
   2. In the Add Data Type dialog, type a name. For the Task Management API example, type Todo.

   3. Optionally, you can provide an example from which API Designer creates the data type’s schema. You can then edit the generated schema.

      For the Task Management API example, start with the following JSON example:

      {
          "id": 1,
          "task": "my task",
          "completed": false
      }

   4. Optionally, you can choose to create a REST Resource with the data type.

   5. Click Save. If you provided an example, API Designer generates a schema from the example:

      
7. Optionally, you can add edit the schema properties and add new ones.

8. For the Task Management API example, create another data type named Task with one property named task of type string.

   

9. For each path, define operations (GET, PUT, POST, DELETE, OPTIONS, HEAD, or PATCH).

   For the Task Management API example, define the operations as described in the following table:

   Table 3.1. Task Management API operations

   Path	Operation	Description	Request	Response
   /todo	POST	Create a new task.	Request Body type: Task	Status Code: 201 Description: Task created Response Body: Todo type
   /todo	GET ALL	Get all tasks.	Not applicable	Status Code: 200 Description: Task deleted Status Code: 400 Description: Task not deleted
   /todo/{id}	GET	Get a task by ID.	Not applicable	Status Code: 200 Description: Task found for ID Response Body: Todo type
   /todo/{id}	UPDATE	Update a task by ID.	Request Body type: Task	Status Code: 200 Description: Completed Status Code: 400 Description: Task not updated
   /todo/{id}	DELETE	Delete a task by ID.	Not applicable	Status Code: 200 Description: Task deleted Status Code: 400 Description: Task not deleted

10. Resolve any issues, as described in Section 3.3.1.2, “Resolving issues in API Designer”.

Procedure

1. Find an issue indicated by an exclamation (!) icon. For example:

   

2. Click the exclamation icon to view a description of the issue. For example:

   

3. Based on the information provided by the issue description, navigate to the location of the issue and fix it.

   For example, open the GET operation and then add a response.

   

   After you add a description, the issue is resolved and the exclamation icon disappears:

   

4. For a summary of all issues:

   1. Click the Issues link in the upper right corner.

      

   2. Click Go to a problem for a specific issue to go to the location of the issue so that you can resolve it.