walkthrough.adoc

Integrator Lab 1 - API Design

In this lab you will use API Designer to create a simple API definition using the OpenAPI Specification. You will learn how to author and download a standards compliant API Specification using Red Hat’s API Designer.

Audience: API Owner, Product Manager, Developers, Architects

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 Red Hat API Designer editor.

Skipping The Lab

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

Credentials:

Your username is: {user-username}
Your password is: openshift

API Designer

• API Designer

Creating APIs with API Designer

1. Launch a new tab on your web browser.

2. Navigate to the Solution Explorer on that tab.

3. Click on the API Designer link.

4. Click on New API, and select New (OpenAPI 3)

   

Did the API successfully get created?

Have your instructor check the Kubernetes pod that contains the API Designer application.

Creating API

You are now in the main screen to edit your APIs. Red Hat API Designer is a graphical, form-based API editor. With API Designr, 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. Create a brand new API by completing the following information:

   • Name: Locations-{user-username}

   • Description: Locations API

     

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

   

3. Fill in the Name field with the value location.Scroll down to 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

   
   

4. API Designer automatically tries to detect the data types from the provided example.

   

   Time to start creating some paths.

Were the data types successfully detected?

Have your instructor check the Kubernetes pod that contains the API Designer application.

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, API Designer suggest a series of available operations for your new path.

4. Click Add Operation under the GET operation.

   

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

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. Click 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 Array and location.

   

10. Click on the No Examples defined tab and click on Add an example link to add a Response Example.

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

    

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

    

12. Click on edit button for Description message, and enter Returns an array of location records as the description. Click the check-mark button to accept the description.

    

Were the HTTP Response, path parameter and GET operation created successfully?

Have your instructor check the Kubernetes pod that contains the API Designer application.

3b: 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 Add 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. Click 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 edit next to No description message, and enter Returns a single location record as the description. Click the check-mark button to accept the description.

    

Was the path created successfully?

Try to redo this section, if any problem persists have your instructor check the Kubernetes pod that contains the API Designer application.

Download the API definition

1. Click the Locations-{user-username} Save As YAML link to download the API spcification.

   

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

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

   

Was the source file created successfully?

Try to redo this section, if any problem persists have your instructor check the Kubernetes pod that contains the API Designer application.

Congratulations! You have created your first API definition based on the OpenAPI Specification using Red Hat’s API Designer. 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? API Designer 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 API Designer 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 API Designer.

You can now proceed to Lab 2.

Notes and Further Reading

• API Designer

  • API Designer

• Apicurio

  • Webpage

  • Roadmap

• OpenAPI

  • OpenAPI Initiative

  • OpenAPI Specification 3.0.2