Chapter 2. Design and develop an API definition with API Designer

You can use API Designer to design and develop a REST API definition that complies with the OpenAPI 2.0 specification.

Prerequisites

  • You created an OpenShift project.
  • You added the API Designer service to your OpenShift project.

2.1. Creating a REST API definition

The following steps describe how to create a REST API definition.

Note
  • You can access the API Designer user interface from Fuse Online or Fuse on OpenShift.
  • For Fuse on OpenShift only, API Designer is stateless which means that it does not save your work between OpenShift sessions. You need to save the API to your local file system between sessions.

About the example

The Task Management API example simulates a simple API that sales consultants might use to track the tasks that they need to do when interacting with customer contacts. Example "to-do" tasks might be "create an account for a new contact" or "place an order for an existing contact". To implement the Task Management API example, you create two paths - one for tasks and one for a specific task. You then define operations to create a task, retrieve all tasks or a specific task, update a task, and delete a task.

Prerequisites

  • You know the endpoints for the API that you want to create. For the Task Management API example, there are two endpoints: /todo and /todo/{id}.
  • For Fuse on OpenShift only, you created an OpenShift project and you added the API Designer service to your OpenShift project.

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. In 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.
  3. To change the API name:

    1. Hover the cursor over the name and then click the edit icon ( 28 ) 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}

      apidesigner paths
  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.

      apidesigner parameter
  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:

      apidesigner datatype schema
  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.

    apidesigner another type
  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 operations

    PathOperationDescriptionRequestResponse

    /todo

    POST

    Create a new task.

    Request Body type: Task

    Status Code: 201

    Description: Task created

    Response Body: Todo type

    /todo

    GET

    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

  11. Resolve any issues, as described in Section 2.2, “Resolving 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.

Additional resources

2.2. Resolving issues in API Designer

When you create and edit an API, API Designer identifies issues that you must resolve with an exclamation (!) icon.

Prerequisites

  • Open an API in API Designer.

Procedure

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

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

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

    apidesigner issuelocate

    After you type a description for the response, the issue is resolved and the exclamation icon disappears:

    apidesigner issuefix
  4. For a summary of all issues:

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

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

      List of issues