lab01

Lab 1

API Design

Create an OpenAPI Specification using Apicurio Studio

• Duration: 10 mins
• Audience: API Owner, Product Manager, Developers, Architects

Overview

As APIs become more widespread in the enterprise, consist design and usage is critically important to improve re-usability. The more re-usable 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?

RedHat is one of the founding members of the Linux Foundation Open API Initiative which is produces the leading standard for REST API specifications. Red Hat consistently uses this format throughout it's tooling, starting with the Apicurio Studio API Design editor.

Skipping The Lab

We know sometimes we don't have enough time to go over step by step on the labs. So here is a short video where you can see how to create an OpenAPI Specification with Apicurio Studio.

If you are planning to skip this lab and follow the next one, here is a link to the specification generated in this lab.

Environment

URLs:

Check with your instruction the GUID number of your current workshop environment. Replace the actual number on all the URLs where you find GUID.

Example in case of GUID = 1234:

https://master.GUID.openshiftworkshop.com

becomes =>

https://master.1234.openshiftworkshop.com

Credentials:

Your username is your asigned user number. For example, if you are assigned user number 1, your username is:

user1

The password to login is always the same:

openshift

Lab Instructions

Step 1: Creating APIs with Apicurio Studio

1. Open a browser window and navigate to:

   http://apicurio-studio.apps.GUID.openshiftworkshop.com/

2. Accept the self-signed certificate if you haven't:

   1. If using Google Chrome click the ADVANCED link.

   

   1. Then click the Proceed to.. link to accept the certificate and add the exception.

   

3. Log in using your designated user and password.

   

4. Click on APIs in the left side navigation menu from the Dashboard page.

   

5. Click on Create New API.

   

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

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

   

7. Click on Create API.

8. 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. Different from other API editor products, Apicurio's Editor is a graphical, form-based 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 definition link under the Definitions.

   

2. Fill in the Name with the location value. Expand the FROM EXAMPLE (optional) to paste the following example:

   • Name: location

   • FROM EXAMPLE:

     {
         "id": 1,
         "name": "International Inc Corporate Office",
         "location": {
             "lat": 51.5013673,
             "lng": -0.1440787
         },
         "type": "headquarter",
         "status": "1"
     }

   

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

   

   Time to start creating some paths.

Step 3: Adding Paths

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 on the Edit button to edit the response details.

   

9. Scroll down again to the bottom of the page. Click on the Add Media Type button to define and configure the response media type.

   

10. Leave application/json as the value of Media Type. Click the Add button.

    

11. Click on the Choose Type combo box to display the different types. First select Array.

    

12. This will enable a second combo box. In this new box, select location from the displayed options.

    

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

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

    

14. 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"
          }
      ]

    

15. Click the Add button.

16. Click the Done button to finish the response editing.

    

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

You can now proceed to Lab 2

Notes and Further Reading

• Apicurio
  • Webpage
  • Roadmap
• OpenAPI
  • OpenAPI Initiative
  • OpenAPI Specification 3.0.1