Chapter 3. Designing and developing an API definition with API Designer

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 API Designer.

   2. For OpenShift 4.x, select Topology and then click the URL link on the apicurito-service-ui icon.

      For OpenShift 3.11, from the list of applications, click the URL for API Designer, for example https://apidesigner-myproject.192.168.64.43.nip.io

      A new browser window or tab opens for API Designer.

      Note

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

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

   By default, API Designer uses the OpenAPI 3 specification. If you want to use the OpenAPI 2 specification, click the arrow next to the New API button and then select OpenAPI 2.

   Note

   If you open an API based on the OpenAPI 2 specification, you can use the API Designer’s Convert to OpenAPI 3 option to convert the API to comply with the OpenAPI 3 specification.

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. Click the checkmark icon to confirm the name change.

4. Optionally:

   • Provide a version number and a description.
   • Add your contact information (name, email address, and URL).
   • Select a license.
   • Define tags.
   • Define one or more servers.
   • Configure 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 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:

      
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 3.1. Task Management API operations

    Path	Operation	Description	Request Body	Response
    /todo	POST	Create a new task.	Media Type: application/json Data Type: Task	Status Code: 201 Description: Task created Response Body: Media Type: application/json Data Type: Todo
    /todo	GET	Get all tasks.	Not applicable	Status Code: 200 Description: List of Tasks
    /todo/{id}	GET	Get a task by ID.	Not applicable	Status Code: 200 Description: Task found for ID Response Body: Media Type: application/json Data type: Task Status Code: 404 Description: No task with provided identifier found.
    /todo/{id}	PUT	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

11. Resolve any issues, as described in Resolving validation issues in API Designer.

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, to fix the "Operation must have at least one response" issue, click the GET operation to open it and then click Add a response.

   

   After you type a description for the response, 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.