From Open API to .Net Core on Openshift

Using Apicurio Studio to design a sample inventory API

This is part 1 of a 2-part story about how to move from designing an Open API specification to deploy the sample .Net Core code generated on Red Hat’s Kubernetes platform Openshift.

This 2-part story not a .Net Core tutorial, and I’m not a .Net Core/C# expert… what is even better to show how easy it is to create .Net Core microservices to run on Openshift taking an API first approach.

TL;DR

First of I’ll show you how to design an API for a simple inventory service using Apicurio Studio. In the next part I’ll show how to generate the code using OpenAPI Generator and how to deploy the code on Openshift.

Tools

In order to design our API we’re going to use API Curio, an online API designer supporting Open API 3.x and Swagger (Open API 2.x)

Please go to API Curio and login (you can user your github/google account to login)

Designing the API

After a successful login you should land in the dashboard area.

Please, click on APIs (left side), there you should be able to see your APIs, none if it’s the first time you use it. Click on Create New API to start designing our Inventory API.

Now give to your API Name, Description, select version Open API 3.0.2 and finally select Blank API as the starting point, as in the next picture.

At this point we have an empty API, so let’s start actually editing the API by clicking on Edit API.

Click on Add a data Type or the plus sign next to Data Types.

The first thing we’re going to do is to create the InventoryItem type, so click on Add a data Type or the plus sign next to Data Types.

In order to create our data type we have to provide a Name a Description and a sample JSON object (although optional we’re are going to use this feature to make the editing somewhat easier). After entering the following data please click on Save.

• Name: InventoryItem
• Description: The root of the InventoryItem type's schema.
• Sample JSON object:

{"itemId":"329299","quantity":35}

Now that we have our InventoryItem data type, it’s time to define the API. Defining the API consist on defining paths like:

• /api/inventory to get all the items in the inventory
• /api/inventory/{itemId} to get a specific item

Let’s create our first path, click on `Add a Path`

Please type /api/inventory and click on Add.

As you can see there are no operations defined yet. As the Inventory API should return all the items with a simple GET with no parameters. To do so let’s define a GET operation by selecting GET first and clicking on Add Operation afterwards.

GET should be selected (blue underlining) by default, if that’s not the case, please make sure it is.

Let’s edit the description and type something like: “Should return all elements as an array of InventoryItems or an empty array if there are none.”

Now if you scroll down a little, you’ll see a warning sign underneath the Responses area. Click on Add a response to add an HTTP 200 response.

Click on Add (200 should be selected by default).

Add a description to the response, for instance: “Should return an array of InventoryItems”.

Click on No response media types defined and then on Add media type

Now, choose application/json.

The answer should be an Array (of JSON objects) of type InventoryItem.

Once you have chosen the proper type, please click on Add Example.

Copy and paste the following example and click on Add.

[{"itemId":"329299","quantity":35},{"itemId":"329199","quantity":12},
{"itemId":"165613","quantity":45},{"itemId":"165614","quantity":87},
{"itemId":"165954","quantity":43},{"itemId":"444434","quantity":32},
{"itemId":"444435","quantity":53}]

That’s all needed related to the first path, let’s do the same for the second. Remember click on the plus sign.

This time we need a path parameter to search for a specific, like this one: /api/inventory/{itemId}

Following up with the path parameter, scroll down to Path Parameters you’ll find that there is one already created (inferred from the path you typed in before). Click on Create to actually create it.

Then set the type of the parameter to String.

We’re all set with regards to parameters, now it’s time to create an operation, again is a GET operation. So click on the Add operation button (make sure GET is selected).

Again, let’s add a description to the action, something like: Returns the item for the id provided or an error

Once again we have a warning in the Responses area we have to take care of. Please click on Add Response

Choose 200 (default) and click Add.

Let’s add a description, something like this: Should return the item for the id provided.

As we did before, we have to add a media type application/json.

Don’t forget to click on Add.

This operation should return an inventory item, so please choose InventoryItem as the response type.

As previously, let’s add an example, named OneItem

{"itemId":"329299","quantity":35}

We have to add another response for the case when we cannot find the item id provided. But before we do, we’re going to add a new type to encode the error as a JSON object. Click on the plus sign to create a new Data Type.

Create a new data type with the following values.

• Name: GenericError
• Description: Generic Error Object.
• Sample JSON object:

{ "code" : "404", "message" : "Item 53 was not found" }

Now let’s add a new response. This time the Status Code needs to be 404.

Add a description as in the next pictures.

And as usual a new media type of type application/json.

This time we have to choose GenericError as the response type.

Finally let’s add a sample JSON object named NotFoundError.

{
   "code" : "404",
   "message" : "Item 53 was not found"
}

And that’s it, we have designed a pretty basic inventory API, including examples, documentations, etc. using Open API 3.x

Now you can export the specification as YAML, JSON, etc.

Next steps

In part 2 you’ll create .Net Core server stubs and deploy your generated code on Openshift.