<img src="../images/agenda-01.png “Login” width=“900” />
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.
As a developer, we need to be familiar with API Design even though it’s not our core capability. Therefore, in this lab we will review Red Hat’s API Designer product, Apicurio, so that we’re familiar with it’s capabilities only.
Red Hat is one of the founding members of the Linux Foundation Open API 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 Design editor.
Open a browser window and navigate to Apicurio. Please ask your Instructor if you do not have the link.
Log in using your designated user and password.
<img src="../images/design-01.png “Login” width=“900” />
Click on APIs in the left side navigation menu from the Dashboard page.
<img src="../images/design-02.png “APIs” width=“900” />
Click on Import API.
<img src="../images/design-03.png “Import API” width=“900” />
Import the API created by your friendly Citizen Integrator:
https://raw.githubusercontent.com/epe105/dayinthelife-integration/master/docs/labs/developer-track/resources/Locations.yaml<img src="../images/design-04.png “Import API” width=“900” />
Click on Import API.
Finally, click on Edit API to walkthrough your newly imported API.
<img src="../images/design-05.png “Edit API” width=“900” />
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 verifying your API.
Time to verify our data definitions for the API. Click on the location/phone{id} link under the Paths.
<img src="../images/design-15.png “Add Definition” width=“900” />
Notice that this API path has a single path parameter (id defined as an int32) and a single GET operation defined. Click on the GET operation, then click the location drop-down which is part of the 200 OK response.
<img src="../images/design-16.png “Definition Name” width=“900” />
Notice that this API path has a single response defined (a 200 OK response) and the type that is returned is a location object.
<img src="../images/design-17.png “Definition Data Types” width=“900” />
Click on the </> location object link under the Data Types section. Notice that the object has a bunch of properties defined which make up the object.
<img src="../images/design-06.png “Add Path” width=“900” />
Click on the source link and notice that we have both YAML and JSON schemas generated by our object design:
<img src="../images/design-07.png “Path” width=“900” />
Click the /locations path. Then click on the source tab. Notice that we have both a GET and POST request defined, together with a couple of example requests. Using a POST method, we can insert a new record into our sample database with Fuse.
<img src="../images/design-23.png “Locations API” width=“900” />
Congratulations! You have imported your first API definition based on the OpenAPI Specification using Red Hat’s Apicurio.
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.
In this lab you used Apicurio Studio to import a simple API definition using the OpenAPI Specification (Swagger 2.0). You learned how to author and download a standards compliant API Specification using Red Hat’s APICurio.