Basics of API Hub for Design

Notice

This is an early access preview of our latest features. Note that during this early access phase, some features you encounter may still be under development and could change. Additionally, certain features and functionalities may or may not be available to you as an early access user.

This tutorial provides a brief overview of API Hub for Design, and walks you through creating and publishing an API definition using API Hub for Design.

Requirements

To complete this tutorial, you need:

  • An API Hub account (during this early access preview, you must be invited to an API Hub account by an admin. In order to invite users to your API Hub organization, follow the instructions here).

  • Basic knowledge of APIs.

What is API Hub for Design?

API Hub for Design allows you to design your APIs – be it public or private APIs. The core principle behind API Hub for Design is Design First, Code Later. That is, you start by laying out your API, its resources, operations, and data models, and once the design is complete you implement the business logic.

API definitions are written in the OpenAPI (formerly known as Swagger) or AsyncAPI format. They are saved in the API Hub for Design cloud and can be synchronized with external systems like GitHub or Amazon API Gateway. You can also collaborate with your team on API Hub for Design, and maintain multiple versions of APIs as they evolve.

In this tutorial, we will walk through an OpenAPI (REST) example, but the process is the same for AsyncAPI.

The My APIs Screen

When you are logged in to API Hub for Design, the My APIs page lists all the APIs you have access to. These are both the APIs you created and the APIs you were invited to collaborate on.

API_screenshot_my_APIs_01.png

Click the image to enlarge it.

To search for existing APIs on API Hub for Design, use the search page that you can access by clicking in the sidebar on the left. This way you can find some great public APIs developed by other API Hub for Design users. See Searching API Hub for Design for the search syntax.Searching API Hub for DesignSearching API Hub for Design

API_screenshot_search_APIs_01.png

Click the image to enlarge it.

To view a specific API, click it in the list.

Open to View

Click the image to enlarge it.

An API page on API Hub for Design is a split view that shows the YAML code of your OpenAPI definition and reference-style API documentation generated from it. The Form Editor allows the user to view the API, while the API documentation - to test API calls directly in the browser. The navigation panel on the left shows a list of operations and models defined in your API and lets you jump to the corresponding place in the YAML code. You can resize the panels by dragging the splitter between them.

API_screenshot_API_edit_panel_01.png

Click the image to enlarge it.

The next step in this tutorial is:

Creating a sample API with API Hub for Design

For designers, the best way to understand API Hub for Design is to create a sample API, so let’s do that. Do not worry about configuring a server. In this tutorial, we will focus on designing an API.

Step 1. Create an API

In the sidebar on the left, click and select Create New API.

API_screenshot_create_API_01.png

Fill in the API information as shown in the image below.

The Specification field specifies the spec format, OpenAPI 3.0.0, OpenAPI 2.0. or AsyncAPI 2.x. Choose OpenAPI 3.0.0.

There are predefined templates, such as Petstore, but now, let’s start with a blank API (no template).

Enter sample as the API name, 1.0.0 as the version, Sample API as the title and an arbitrary description. Be sure to change the Auto Mock API slider to the OFF position.

API_screenshot_create_API_02.png

Click Create API. The API Hub for Design Form Editor will open, pre-populated with the API metadata you have entered.

Each API definition starts with the API version. In our example it is openapi: 3.0.0.

openapi: 3.0.0

The next section, info, contains the metadata about the API – the API title, description, version, and so on. The info section may also include contact information, license, and other details.

info:
  title: Sample API
  version: 1.0.0
  description: This is a sample API.

The paths section is where you define the API operations. We will populate it later.

paths: {}

Step 2. Add server info

Next, we need to define the API server address and the base URL for API calls. Suppose the API will be located at https://api.example.com/v1. This can be described as:

servers:
  - url: https://api.example.com/v1

Add these lines between info and paths, like this:

API server and base URL

Step 3. Define a GET operation

Suppose our API is intended to manage a list of users. Each user has an ID, and the API needs an operation to return the user by their ID. That would be a GET request like this one:

GET /users/3
GET /users/15

Using Swagger, we can describe this GET operation as follows. The {userId} part in /users/{userId} indicates the path parameter, that is, a URL component that can vary.

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID
      responses:
        '200':
          description: OK

Paste the code above to the editor, replacing the paths: {} line. Your spec should look like this:

API specification with a GET operation

Click the image to enlarge it.

Note that as you edit the spec, API Hub for Design automatically updates the preview on the right.

Step 4. Define parameters

Our API operation GET /users/{userId} has the userId parameter that specifies the ID of the user to return. To define this parameter in your spec, add the parameter section as follows:

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the user to return
          schema:
            type: integer
      responses:
        '200':
          description: OK

This code specifies the parameter name (the same as the one used in the URL path), type, description and whether it is required. in: path means the parameter is passed as part of the URL path (GET /users/15), as opposed to, say, query string parameters (GET /users?id=15).

Note that after you add the parameters section, the preview is updated to reflect the newly added parameter information:

Parameter information

Click the image to enlarge it.

Step 5. Define responses

Next, we need to describe possible responses for the API call. A response is defined by an HTTP status code, description and optional schema (a data model for the response body, if any).

Suppose a successful call to GET /users/{userId} returns HTTP status 200 and this JSON object:

{
  "id": 42,
  "name": "Arthur Dent"
}

To describe this response, add the content section under the 200 response as follows. The content section specifies that the response contains JSON data (application/json). Note the schema element – it describes the structure of the response body, such as the properties of the returned JSON object.

paths: 
  /users/{userId}:
    get:
      ...
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

You can also describe various error codes that can be returned by an API call:

      responses:
        ...
        '400':
          description: The specified user ID is invalid (e.g. not a number)
        '404':
          description: A user with the specified ID was not found

The complete spec should now look like this:

Operation responses

Click the image to enlarge it.

Step 6. Publish the API

Our API is finished, so let’s publish it. Publishing is a way to tell people that the API is in a stable state, it is going to work as designed and is ready to be consumed by applications. Do not worry about configuring a server – this tutorial is about designing the API specification without actual implementation.

To publish the API, click the drop-down arrow next to your API version, and then click publish.png.

Congratulations! You have published your first API on API Hub for Design! You can copy its address from the browser’s address bar and share it with others. Since this is a public API, anyone who has a link can view it, and it will show up in the search results on API Hub for Design. You can make your API private if your API Hub plan allows this.

Note that published APIs become read-only, and can only be edited if the API is unpublished again. It is OK to unpublish an API temporarily if you need to improve the description text or fix typos. But for breaking changes like new operations or parameters, you should start a new version instead by using the Add Version command in the API Hub for Design editor. API Hub for Design lets you maintain multiple versions of an API specification, so you can work on the next API version while keeping the published version (the “production” version) intact.

Other things to do in the API Hub for Design editor

API Hub for Design editor is not just an editor, it provides tools for managing your API specification and integrating it into your workflow. Let’s take a quick look at other available commands:

  • The Settings menu lets you rename the API, fork it, or transfer it to another owner.

  • The Export menu lets you generate server and client code for your API to help you get started with implementation. Here you can also download your OpenAPI definition as YAML or JSON.

Reviewing a Resource File

For consumers who do not have the necessary privileges to create/update APIs, API Hub for Design allows you to access resource files (APIs, templates, domains) in read-only mode. To review a resource file, simply click on it in the main screen.

API_screenshot_open_API_01.png

Once you open the API definition, you can review it. If you do not know how to read the screen, consult one of the tutorials.Get Started

API_screenshot_API_edit_panel_01.png

If your API Hub for Design orgaization owner has allowed it, you can insert comments into resource files. Click here for more information about comments.

What’s next

Learn OpenAPI 3.0 syntax

Learn OpenAPI 2.0 syntax

Learn AsyncAPI syntax

Proceed with API design and implementation

See Also

Publication date: