Designing APIs with Apicurito

1. In a command window, log in to the OpenShift server:

   oc login -u developer -p developer

2. Create a new project namespace. For example, the following command creates a new project named test:

   oc new-project test

3. In your web browser, open the OpenShift console and log in with your credentials (for example, username developer and password developer).

4. Click Catalog. In the Catalog search field, type Apicurito and then select Red Hat Fuse Apicurito.

   

   The Information step of the Red Hat Fuse Apicurito wizard opens.

5. Click Next.

   The Configuration step of the Red Hat Fuse Apicurito wizard opens.

6. In the Image Stream Namespace field, type openshift.

   
7. In the ROUTE_HOSTNAME field, type the external hostname that allows you to access the Apicurito instance, for example apicurito-myproject.192.168.64.43.nip.io.

8. Accept the default values for the rest of the settings in the Configuration step and click Create.

   The Results step of the template wizard opens.

   
9. Click Close.

10. In the OpenShift web console, in the My Projects pane, select the project, for example select test.

    The project’s Overview tab opens, showing the apicurito-ui application.

11. Click the arrow to the left of the apicurito-ui deployment to expand and view the deployment details:

    

12. Click the link for the Aplicurito instance, for example https://apicurito-myproject.192.168.64.43.nip.io.

    Apicurito opens in a new web browser window or tab:

    

Procedure

1. If you are using Fuse Online, skip to step 2.

   If you are using Fuse on OpenShift:

   1. Log in to your OpenShift web console and then open the project that contains Apicurito.

   2. In the list of applications, click the URL for Apicurito, for example https://apicurito-myproject.192.168.64.43.nip.io

      

      A new browser window or tab opens for Apicurito:

      
      Note

      Because Apicurito is a “light” version of the Apicurio Studio open source project, "Apicurio" shows in the Apicurito interface.

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

3. 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.

4. Optionally:

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

5. 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}

     

6. 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.

      

7. 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 Apicurito 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, Apicurito generates a schema from the example:

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

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

   

10. 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 2.1. Task Management API oeprations

    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/{id}	GET	Get a task by ID.	Not applicable	Status Code: 200 Description: Task found for ID Response Body: Todo type
    /todo/{id}	DELETE	Delete a task by ID.	Not applicable	Status Code: 200 Description: Task deleted Status Code: 400 Description: Task not deleted

11. Resolve any issues, as described in Section 2.2, “Resolving issues in Apicurito”.

12. For Fuse on OpenShift only, save your API specification by clicking Save As and then select JSON or YAML format.

    The JSON or YAML file is downloaded to your local download folder. The default filename is openapi-spec with the appropriate file extension.

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.

      

Procedure

1. In your OpenShift web console, open the project that contains Apicurito.

2. Open the Apicurito console. In the list of applications for the project, click the URL under apicurito. For example: https://apicurito-myproject.192.168.64.38.nip.io

   

   The Apicurito console opens in a separate web browser tab or window:

   

3. Click Open API.

   A file manager window opens.

4. In the file manager window:

   1. Navigate to the folder that contains the existing OpenAPI definition file, for example, openapi.json.

   2. Select the OpenAPI definition file and then click Open.

      The OpenAPI definition opens in the Apicurito console. For example:

      

1. Click Generate.
2. Select Fuse Camel Project from the drop-down list.

Procedure

1. Unzip the Apicurito-generated camel-project.zip file to a temporary folder.
2. Open Red Hat Developer Studio.
3. In Developer Studio, select File → Import.
4. In the Import dialog, select Maven → Existing Maven Projects.
5. Open the project’s camel-context.xml file in the editor view.

6. Click the REST tab to edit the Rest DSL components.

   For information on defining REST services, see the "Defining REST services" section of the Apache Camel Development Guide.

   For information on extending JAX-RS endpoints with Swagger support, see the Apache CXF Development Guide.

   For information on using the Fuse Tooling REST editor, see the "Viewing and editing Rest DSL components" section of the Tooling User Guide.

7. In the Design tab, edit the Camel routes.

   For information on editing Camel routes, see the "Editing a routing context in the route editor" section of the Tooling User Guide.

1. Log in to your OpenShift cluster:

   $ oc login -u developer -p developer

2. Create a new OpenShift project for the project. For example, the following command creates a new project named test-deploy.

   $ oc new-project test-deploy

3. Change the directory to the folder that contains your Fuse Camel project (for example, myworkspace/camel-project) :

   $ cd myworkspace/camel-project

4. Build and deploy the project to the OpenShift cluster:

   $ mvn clean fabric8:deploy -Popenshift

5. In your browser, open the OpenShift console and navigate to the project (for example, test-deploy). Wait until you can see that the pod for the camel-project application has started.
6. On the project’s Overview page, locate the URL for the camel-project application. The URL uses this form: http://camel-project-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io.
7. Click the URL to access the service.

1. Edit the Fuse project’s pom.xml file to include the fabric8-maven-plugin dependency, as shown in this example:

   <plugin>
           <groupId>org.jboss.redhat-fuse</groupId>
           <artifactId>fabric8-maven-plugin</artifactId>
           <version>${fuse.version}</version>
           <executions>
             <execution>
               <goals>
                 <goal>resource</goal>
                 <goal>build</goal>
               </goals>
             </execution>
           </executions>
     </plugin>

   The Fabric8 Maven Plugin runs the Fabric8 service discovery enricher if certain project-level conditions are met (for example, the project must be a Camel Rest DSL project). You do not need to specify the Fabric8 service discovery enricher as a dependency in the pom.xml file, unless you want to customize the enricher’s behavior (as described in Section 4.2, “Customizing the API service annotation values”.)

2. In the Fuse Rest DSL project’s camel-context.xml file, specify the following attributes in the restConfiguration element:

   • scheme: The scheme part of the URL where the service is hosted. You can specify “http” or “https”.
   • contextPath: The path part of the URL where the API service is hosted.

   • apiContextPath: The path to the location where the API service description document is hosted. You can specify either a relative path if the document is self-hosted or a full URL if the document is hosted externally.

     The following excerpt from an example camel-context.xml file shows annotation attribute values in the restConfiguration element:

     <?xml version="1.0" encoding="UTF-8"?>
     <beans xmlns="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="
            http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
            http://camel.apache.org/schema/spring       http://camel.apache.org/schema/spring/camel-spring.xsd">
     
         <camelContext xmlns="http://camel.apache.org/schema/spring">
             <restConfiguration component="servlet" scheme="https"
                   contextPath="myapi" apiContextPath="myapi/openapi.json"/>
     ...

1. Open your Fuse project’s pom.xml file in an editor of your choice.

2. Locate the fabric8-maven-plugin dependency, as shown in this example:

   <plugin>
           <groupId>org.jboss.redhat-fuse</groupId>
           <artifactId>fabric8-maven-plugin</artifactId>
           <version>${fuse.version}</version>
           <executions>
             <execution>
               <goals>
                 <goal>resource</goal>
                 <goal>build</goal>
               </goals>
             </execution>
           </executions>
     </plugin>

3. Add the Fabric8 service discovery enricher as a dependency to the Fabric8-Maven plugin as shown in the following example.

   <plugin>
     <groupId>org.jboss.redhat-fuse</groupId>
     <artifactId>fabric8-maven-plugin</artifactId>
     <version>${fuse.version}</version>
     <executions>
       <execution>
         <goals>
           <goal>resource</goal>
           <goal>build</goal>
         </goals>
       </execution>
     </executions>
     <dependencies>
       <dependency>
         <groupId>io.acme</groupId>
         <artifactId>myenricher</artifactId>
         <version>1.0</version>
         <configuration>
           <enricher>
             <config>
               <f8-service-discovery>
                 <scheme>https</scheme>
                 <path>/api</path>
                 <descriptionPath>/api/openapi.json</descriptionPath>
               </f8-service-discovery>
             </config>
           </enricher>
         </configuration>
         </dependency>
     </dependencies>
   </plugin>

4. Save your changes.