Getting started with Red Hat OpenShift API Designer

• Red Hat account
• Current subscription or trial access to Red Hat OpenShift Dedicated or Red Hat OpenShift Service on AWS
• A running Service Registry instance (required only if you want to export to Service Registry, see the Getting started with Service Registry quick start)

The OpenShift API Management service adds full API lifecycle management capabilities to Red Hat OpenShift Dedicated and Red Hat OpenShift Service on AWS. Red Hat hosts and manages both the service and the underlying OpenShift platform.

Based on the Red Hat 3scale API Management platform, the service includes API traffic control and API program management solutions like analytics, access control, developer workflows, and more, so you can:

• Build an API management program to secure and share APIs with internal and external consumers, then monitor and control usage
• Adopt an API-first approach to reuse existing systems or create modern applications that work across hybrid cloud environments
• Rapidly develop, deploy, and scale microservices-based, integrated applications through a single DevOps pipeline

In the following sections, we’ll give you some ways you can use the OpenShift API Management web console to accomplish some of these goals. 

Use the Red Hat OpenShift API Designer web console to create an OpenAPI or AsyncAPI definition.

1. In the Red Hat OpenShift API Designer web console, click Create design.
2. Complete the form to provide the following details for the new design:
   1. Name: Enter a unique design name, such as My API Design.
   2. Description (Optional): Enter a short description of the design.
   3. Type: Accept the default value OpenAPI, or select another API type from the list.
   4. Version (OpenAPI only): Accept the default value 3.0.2, or select another version from the list.
   5. Template: Select the Pet Store Example template, or select another template from the list.
3. Click Create. The new API design opens in the design editor.
4. Select the design title and click the pen icon. Change the design title to Orders and click the Save changes icon.
   
   NOTE: Editing the design title does not change the design name. To rename a design, click Actions > Edit design metadata, edit the design name, and click Save.
5. Click the Design tab, and optionally edit the design as follows:
   1. Provide a version number and a description.
   2. (AsyncAPI only) Define terms of service.
   3. Add your contact information: name, email address, and URL.
   4. Select a license.
   5. (OpenAPI only) Define tags.
   6. Define one or more servers.
   7. Configure a security scheme.
   8. (OpenAPI only) Specify security requirements.
   9. (OpenAPI only) Configure vendor extensions.
6. Click the Source tab, and review the live preview of the design. The content of the Source tab automatically updates when you edit values on the editor page.
7. (Optional) To see the changes that you made since the last save, click Actions > Show design changes.
8. (Optional) In the left pane of the design editor, you can add the following items:
   1. (OpenAPI only) Resource paths, data types, and responses
   2. (AsyncAPI only) Channels, data types, messages, operation traits, and message traits
9. Click Save.

The new design is listed on the API and Schema Designs page. You can use the options icon (three vertical dots) to view or edit the design details, edit the design content, export the design to Red Hat OpenShift Service Registry, download the design to a file, or delete the design.

Use the Red Hat OpenShift API Designer web console to create an Apache Avro, JSON Schema, or Google Protocol Buffers (Protobuf) event schema.

1. In the Red Hat OpenShift API Designer web console, click Create design.
2. Complete the form to provide the following details for the new design:
   1. Name: Enter a unique design name, such as My Schema Design.
   2. Description (Optional): Enter a short description of the design.
   3. Type: From the list, select Apache Avro, or select another schema type.
3. Click Create. The new schema design opens in the design editor.
4. Edit the design source to provide your content.
5. (Optional) To see the changes that you made since the last save, click Actions > Show design changes.
6. (Optional) For Apache Avro or JSON Schema designs, you can click Actions > Format design content to insert spaces and tabs that align your design content correctly.
7. Click Save.

The new design is listed on the API and Schema Designs page. You can use the options icon (three vertical dots) to view or edit the design details, edit the design content, export the design to Red Hat OpenShift Service Registry, download the design to a file, or delete the design.

You can import an event schema or API definition into Red Hat OpenShift API Designer from a URL, from a file, or from a running Red Hat OpenShift Service Registry instance.

In addition to the prerequisites for this Quick Start, this step requires:

• You’re logged in to the Red Hat OpenShift API Designer web console at https://console.redhat.com/application-services/api-designer/.
• You can access a running OpenShift Service Registry instance in your organization, if you want to import from Red Hat OpenShift Service Registry. For more information, see Getting started with Red Hat OpenShift Service Registry.

Steps:

1. In the Red Hat OpenShift API Designer web console, click Import design, and then click one of the following options:
   1. Import from Service Registry: From the instances list, select a Service Registry instance. Browse the list of artifacts for that instance, and select an artifact.
   2. Import from URL: Enter a valid and accessible URL, and click Fetch.
   3. Import from file: Click Browse and select a file, or drag and drop a file.
2. When prompted, provide additional information such as version (OpenAPI only), name, type, and description in the import dialog. You can overwrite any autopopulated values.
3. Click Import. The design editor opens automatically.

You can test that your schema or API design content is valid and compatible with existing content by applying the rules of an existing Red Hat OpenShift Service Registry instance. You can test the design while working in the Red Hat OpenShift API Designer editor, without exporting the design to Red Hat OpenShift Service Registry.

In addition to the prerequisites for this Quick Start, this step requires:

• You’re logged in to the Red Hat OpenShift API Designer web console at https://console.redhat.com/application-services/api-designer/.
• You’ve created or imported a design in OpenShift API Designer.
• You can access a running OpenShift Service Registry instance in your organization. Within that instance, you know the artifact ID of an artifact with the required rules configured. For more information, see Getting started with Red Hat OpenShift Service Registry.

Steps:

1. On the API and Schema Designs page of the Red Hat OpenShift API Designer web console, select the design that you want to test.
2. Click the options icon (three vertical dots), and click Edit design content to open the design editor.
3. From the Actions menu, click Run Service Registry check.
4. From the Registry instance list, select a Service Registry instance.
5. In the Group and ID fields, specify the artifact details.
6. Click Test.

When you’re happy with the changes to your Red Hat OpenShift API Designer event schema or API definition, and you want to use the design in your application, you can export the content to an existing Red Hat OpenShift Service Registry instance.

In addition to the prerequisites for this Quick Start, this step requires:

• You’re logged in to the Red Hat OpenShift API Designer web console at https://console.redhat.com/application-services/api-designer/.
• You’ve created or imported a design in OpenShift API Designer.
• You can access a running OpenShift Service Registry instance in your organization. For more information, see Getting started with Red Hat OpenShift Service Registry.

Steps:

1. On the API and Schema Designs page of the Red Hat OpenShift API Designer web console, select the design that you want to export.
2. Click the options icon (three vertical dots), and click Export design to Service Registry.
   
   NOTE: You can also select Export design to Service Registry from the Actions menu in the design editor.
3. Complete the form to specify where to save the new design. Provide the following details:
   
   NOTE: If the design was originally imported from Red Hat OpenShift Service Registry, the fields are prepopulated with the details of the original OpenShift Service Registry instance, and the Version field is blank.
   1. Registry Instance: Select the required instance from the list.
   2. Group (Optional): Enter a unique group name such as my-org to organize the artifact in a named collection. Each group contains a logically related set of schemas or API designs, typically managed by a single entity, belonging to a particular application or organization.
      
      NOTE: Specifying a group is optional when using the web console. If no group is specified, Service Registry uses the default group.
   3. ID (Optional): Enter a unique ID for this artifact, such as my-id. If you don’t specify a unique artifact ID, Service Registry generates one automatically as a UUID.
   4. Version (Optional): Specify the version number. If you don’t specify a version number, Service Registry sets the version to 1 for the first version, or increments the latest version by 1 for subsequent versions.
4. Click Export. The exported design is listed on the artifacts page of the specified Service Registry instance.

For additional information on getting started with OpenShift API Designer, visit the quick start hub on console.

Go to Quick start hub