Skip to main content

Unit 6: Create API Namespace

Tags:
🎯Overview

In this course you will learn about the basics of API namespaces and how to create one.

Outline​

In the IBM DevOps Solution Workbench you can design every aspect of your API within an API Namespace. This includes endpoints, operations (GET, POST, PUT, DELETE) for each endpoint, as well as the operation parameters, request bodies, responses, and contained schemas of various types. When working with APIs in the IBM DevOps Solution Workbench, a specification will be generated automatically in the OpenAPI 3 format. This specification can be used by consumers to quickly discover the offered functionality. When creating an API Namespace you can also make use of an existing OpenAPI 3 specification file; you can import the file so that the elements of the API namespace are generated for you.

Prerequisites​

You have successfully completed the Preparation section in the Course Introduction.

  1. Open your workspace in the Solution Designer.
  2. Find your imported project and open it by clicking on it.
❗️Alternative starting point for your training

If you rather want to use this course as a starting point of your training, you can use a different asset where courses for designing the domain namespace are already completed.
In this case - depending on the chosen implementation language - use either asset "Order_Java_Design_0.2" or "Order_TypeScript_Design_0.2" to create a new project and to continue your training.
You can look up how to create a new project from the Order assets in the Preparation section in the Course Introduction.

Exercise​

Estimated time: 5 minutes
Exercise goal: After completing this course you are able to create an API namespace.
Supported languages: Java and TypeScript

❗️important

In order to provide you with some artefacts that you will need in the following courses, the API namespace is already prepared. The following descriptions therefore only illustrate the steps for creating an API namespace without the need to create it yourself.

ℹ️note

This course shows you how to create an API namespace from scratch. If there is already an existing OpenAPI 3.0 specification, you can also create an API namespace from it.

Step 1: Create a new API Namespace​

API Namespace Screenshot 1

Navigate to the overview of your Domain Service Project and click on the "Create namespace" button.

API Namespace Screenshot 2

Select the "API Namespace" option.

API Namespace Screenshot 3

Enter the general information for the new namespace. Click on "Next".

API Namespace Screenshot 4

Add further details as shown above and click on "Next".

API Namespace Screenshot 5

Select the "Supported API specification" (OpenAPI 3.0) and click on "Create".

API Namespace Screenshot 6

The new API Namespace is now created.

❗️info

The data entered in "API Information" has a direct effect on the metadata in the API specification and is displayed in the Swagger UI of the service.

❗️API Specification

OpenAPI 3.0 is the preferred format for most use cases. However, if you want to enable easy integration with IBM BAW, Swagger 2.0 needs to be chosen.

🌟Congratulations!

You have learned how to create an API namespace! Now you are able to perform the first steps in designing your own API with the IBM DevOps Solution Workbench.

What's next?​

In the next courses you will learn how to design API Schemas and to design API Paths and Operations.

Please find more information about API Namespaces and REST APIs: