Chapter 2. Design and develop an API definition with Apicurito

Procedure

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.

3. Click New API.

   A new API page opens.

   

   By default, the API name is New API, the version is 1.0, and the input and output types are application/json.

4. 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 AddressBook API.
   3. Click Save.

5. Optionally:

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

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

   For the AddressBook API example, create two paths:

   • A path for addresses: /addresses

   • A path for a specific address by ID: /addresses/{addressId}

     

7. Specify the type of any path parameters.

   For the addressID parameter example:

   1. In the Paths list, click /addresses/{addressId}.

      The addressId parameter appears in the PATH PARAMETERS section.

      
   2. Click Create, and then click Edit.
   3. For the type, select string.
   4. Accept string for the format, and then click OK.

8. 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 example Address.

   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 AddressBook API example, start with the following JSON example:

      {
      "Id" : "12345",
      "City" : "Boston",
      "State" : "MA"
      }

      
   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:

      

      You can add edit the properties and add new ones, for example street, zipcode, and country.

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

   For the AddressBook API example, define the following operations:

   • /addresses path:

     • GET - Lists all addresses.
     • POST - Adds an address.

   • /addresses/{addressId} path:

     • GET - Gets an address.
     • PUT - Updates an address.
     • DELETE - Deletes an address.

10. For each operation define a response.

    For the AddressBook API example:

    • To define a response for the /addresses GET operation:

      1. Click the green GET button.
      2. Click Add a response.
      3. For Response Status Code, select 200 and then click Add.

    • To define a response for the /addresses POST operation:

      1. Click the POST button.
      2. For Request Body Type, select Address.
      3. For Response, click Add a response.
      4. For Response Status Code, select 201 Created and then click Add.

11. For each response, provide a description.

    For example:

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

13. Click Save As → Save as JSON.

    The JSON file is downloaded to your local download folder. The default filename is openapi-spec.

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 PUT operation and then add a description for the 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.