Lab 01 - API Design

Return to Workshop

Lab 1

API Design

Create an OpenAPI Specification using Apicurio Studio




Overview

As APIs become more widespread in the enterprise, consistent design and usage is critically important to improve reusability. The more reusable APIs are, the less friction there is for other internal or external teams to make progress. Having design standards and tools baked into the API development and maintenance process is a very powerful way to enable this consistency.

Why Red Hat?

Red Hat is one of the founding members of the Linux Foundation OpenAPI Initiative (OAI) which produces the leading standard for REST API specifications. Red Hat consistently uses this standard throughout its tooling, starting with the Apicurio Studio API Designer editor.

Lab Instructions

Step 1: Creating APIs with Apicurio Studio

  1. Open a browser window and navigate to Apicurio. Please ask your Instructor if you do not have the link.

  2. Log in using your designated user and password.




  3. Click on Create New API.




  4. Create a brand new API by completing the following information:

    • Type: Open API 3.0.2
    • Name: Locations-UserX (Replace X with your user number)
    • Description: Locations API




  5. Click on Create API.

  6. Finally, click on Edit API to start editing your newly created API.




Step 2: Editing APIs

You are now in the main screen to edit your APIs. Apicurio is a graphical, form-based API editor. With Apicurio you don't need master in and out all the details of the OpenAPI Specification. It allows you to design beautiful, functionals APIs with zero coding.

Let's start crafting your API.

  1. Time to prepare our data definitions for the API. Click on the Add a datatype link under the Data Types.




  2. Fill in the Name field with the value location. Expand the Enter the JSON Example (optional) to paste the following example, then click Save:

    • Name: location
    • JSON Example:

      {
          "id": 1,
          "name": "International Inc Corporate Office",
          "location": {
              "lat": 51.5013673,
              "lng": -0.1440787
          },
          "type": "headquarter",
          "status": "1"
      }
      
    • Choose to create a REST Resource with the Data Type: No Resource




  3. Apicurio automatically tries to detect the data types from the provided example.




    Time to start creating some paths.

Step 3: Adding Paths

3a: Add /locations path with GET method

The /locations path with an HTTP GET method will return a complete set of all location records in the database.

  1. Click on the Add a path link under the Paths section. APIs need at least one path.




  2. Fill in the new resource path with the following information:

    • Path: /locations




  3. Click Add.

    By default, Apicurio suggest a series of available operations for your new path.

  4. Click Create Operation under the GET operation.




  5. Click on the green GET operation button to edit the operation information.




    As you can notice, Apicurio Editor guides you with warning for the elements missing in your design.

  6. Click on the Add a response link under Responses to edit the response for this operation.




  7. Leave the 200 option selected in the Response Status Code combo box and click on Add.




  8. Scroll down to the bottom of the page. Move your mouse over the 200 OK response to enable the options. Click the No response media types defined drop-down. Now click on the Add Media Type button.




  9. Click on the Add button to accept application/json as the Media Type.




  10. Click on the Type dropdown and select Array and location.




  11. Click the Add an example link to add a Response Example.

    This will be useful to mock your API in the next lab.




  12. Fill in the information for your response example:

    • Name: all
    • Example:

      [
          {
              "id": 1,
              "name": "International Inc Corporate Office",
              "location": {
                  "lat": 51.5013673,
                  "lng": -0.1440787
              },
              "type": "headquarter",
              "status": "1"
          },
          {
              "id": 2,
              "name": "International Inc North America",
              "location": {
                  "lat": 40.6976701,
                  "lng": -74.259876
              },
              "type": "office",
              "status": "1"
          },
          {
              "id": 3,
              "name": "International Inc France",
              "location": {
                  "lat": 48.859,
                  "lng": 2.2069746
              },
              "type": "office",
              "status": "1"
          }
      ]
      




  13. Click on the drop-down next to the No description message, and enter Returns an array of location records as the description. Click the check-mark button to accept the description.




  14. Click on the green GET operation button to highlight the list of operations.




3b: Update /locations path with POST method

The HTTP POST method will allow us to insert a new locations record into the database.

  1. Click on the Create Operation link under POST to create a new POST operation.




  2. Click the orange POST button to edit the operation.




  3. Click the Add a response link.




  4. Set the Response Status Code value to 201. Click Add.




  5. Click on the drop-down next to the No description message, and enter Creates a new location record as the description. Click the check-mark button to accept the description.




  6. Scroll down to the bottom of the page. Move your mouse over the 201 Created response to enable the options. Click the No response media types defined drop-down. Now click on the Add Media Type button.




  7. Click on the Add button to accept application/json as the Media Type.




  8. Click on the Type dropdown and select location.




3c: Add /locations/{id} path with GET method

The /locations/{id} path will return a single location record based on a single id parameter, passed via the URL.

  1. Now we need to create another path. Click on the + symbol to add a new path, then enter /locations/{id} for the Path property. Click Add.




  2. Scroll over the id Path Parameter value, then click the Create button.




  3. Click the drop-down arrow, then update the id Path Parameter by selecting Integer as the Type and 32-Bit Integer as the sub-type.




  4. Click on the Create Operation button underneath GET, then click the green GET button.




  5. Click on the Add a response link under Responses to edit the response for this operation.




  6. Leave the 200 option selected in the Response Status Code combo box and click on Add.




  7. Scroll down to the bottom of the page. Move your mouse over the 200 OK response to enable the options. Click the No response media types defined drop-down. Now click on the Add Media Type button.




  8. Click on the Add button to accept application/json as the Media Type.




  9. Click on the Type dropdown and select location.




  10. Click on the drop-down next to the No description message, and enter Returns a single location record as the description. Click the check-mark button to accept the description.




3d: Add /locations/phone/{id} path with GET method

The /locations/phone/{id} path will return a single location record based on a single phone number parameter, passed via the URL.

  1. Now we need to create another path. Click on the + symbol to add a new path, then enter /locations/phone/{id} for the Path property. Click Add.




  2. Click on the Create Operation button underneath Get, then click the green Get button.




  3. Scroll down to the id path parameter to highlight the row, and click the Create button that appears.




  4. Click the drop-down arrow next to No Type, then update the id Path Parameter by selecting Integer as the Type and 32-Bit Integer as the sub-type.




  5. Click on the Add a response link under Responses to edit the response for this operation.




    )

  6. Leave the 200 option selected in the Response Status Code combo box and click on Add.




  7. Scroll down to the bottom of the page. Move your mouse over the 200 OK response to enable the options. Click the No response media types defined drop-down. Now click on the Add Media Type button.




  8. Click on the Add button to accept application/json as the Media Type.




  9. Click on the Type dropdown and select location.




  10. Click on the drop-down next to the No description message, and enter Returns a location record as the description. Click the check-mark button to accept the description.




Step 4: Download the API definition

  1. Click the Locations-UserX link to return to the API admin page.




  2. To start using your new API definition, display the API menu from the kebab link. Click the Download (YAML) option from the menu.




  3. This will start the download of your API definition file. It could take a few seconds to start the download. Save it to your local disk drive.

  4. You can open the file with any text editor. Take a look at the source file. Everything is there.




Congratulations! You have created your first API definition based on the OpenAPI Specification using Red Hat's Apicurio. Don't lose track of the file, you will use this definition for your next lab.

Steps Beyond

So, you want more? Did you notice the link source when editing the Paths or the Definitions? Get back to the API editor and follow the link. What do you see? Apicurio lets you follow the form-based editor or go one step beyond and also lets you direct edit the source of your API definition.

Summary

In this lab you used Apicurio Studio to create a simple API definition using the OpenAPI Specification. You learned how to author and download a standards compliant API Specification using Red Hat's APICurio.

Notes and Further Reading

Return to Workshop