How Ballerina OpenAPI Tool addresses your Code-First and Design-First API Approaches

Are you the person who is interested in going your system implementation with API? If you are treating your APIs as First-Class Citizens in your system. I do not doubt you are knowing two main approaches Design First and Code First, you can take to implement your APIs. Don’t worry if you are not familiar with these two schools of thought 😃. I’m here to make you aware of it and this article, I use to discuss how ballerina addresses these two approaches.

What is `Design First Approach`?

Let me give a summary of what is Design-First. The Design-First approach is a relatively newly introduce approach to API development.

The Design First approach advocates for designing the API’s contract first before writing any code.

Let’s assume one company has a business opportunity. First, in SDLC, they need strategic analysis. Then developers get the idea of the requirements and come up with the final objectives with the business opportunity as a first cut. Later they document their requirements with a human-readable contract using OpenAPI(swagger 2.0/3.0). Finally, the Developer can implement the APIs following the aforementioned contract. :)

Below diagram show Design-First Approach (Figure 01)

Figure 01: Design-First Approach.

This approach will be useful when developer experience is matters and this helps to decrease the learning curve of integrating the API consistent. Another advantage of this approach is when you have critical API requirements then you can follow this and come up with the contract the end consumer can understand. To maintain good communication with the team you can use these, because having a powerful transparent API contract may be useful to all the developers in your team to communicate their implementing task properly.

How Ballerina address the `Design First Approach`

In ballerina, we have Ballerina-OpenAPI Tool to handle all your APIs approaches.

Let me explain how we fulfil your Design First approach. In Ballerina-OpenAPI Tool, We have one approach OpenAPI-To-Ballerina with the below command.

bal openapi -i <openapi-contract-path> 
               [ --tags: tags list]
               [ --operations: operationsID list] 
               [ --mode service|client ]
               [(-o| --output): output file path]

Here you only need to provide your API documentation as a YAML or JSON file, then It creates your services according to your contract and offers you this with service skeleton, client stub with record schema ballerina files (Figure 02).

Figure 2: Ballerina OpenAPI-to-Ballerina Command output

If you only need to have a service Skelton or client stub file instead of having both, you can use “- -mode” option to set your requirements.

bal openapi -i <your contract (yaml or json) --mode <service/client>
ex: bal openapi -i petstore.yaml --mode service

If you are interested in creating a file for only selected tags and operations can follow this command.

bal openapi -i <contract> --tags <tags> 
bal openapi -i <contract> --operations <operationIds> 

If we filter our service by giving `list` tag

bal openapi -i openapi.yaml --tags list

Our service file contains only `get` operation with the service path `/pets`.

I suppose you have a fair idea about the Design First approach and how you can use the ballerina OpenAPI tool for your design First approach.

You can refer openapi to ballerina example for more details.

Now we can continue our article with the Code First approach,

What is the `Code First Approach`?

Based on the business plan, Developer can implement their APIs directly, then the developer can convert their APIs into a human-readable or machine-readable documents such as Swagger documents. This process is called as Code First Approach. This is the traditional approach developers used to implement their system 😇.

Figure 02: Code-First Approach.

Now we can look where we can use Code First Approach. When you are in a process you need to deliver your implementation or system speedy that time you better go with Code First approach if you are good with API design knowledge. If the API is used only for internal use in your team and enrich with few endpoints, that time you can go with this approach.

How Ballerina address the `Code First Approach`

You can export your Ballerina service to an OpenAPI Specification 3.0 definition. Using the below command.

bal openapi -i <ballerina-file-path> 
               [(-o| --output) output openapi file path]

Example : bal openapi -i petstore.bal

For having a better contract from your service, make sure the input Ballerina service should be defined using the basic service and resource-level HTTP annotations.

If you need to document an OpenAPI contract for only one given service when the ballerina file has many services, then you can use ‘- -service/-s’ option to generate your contract.

bal openapi -i <ballerina-file-path> (-s | --service) <service-name>

Let's take the below ballerina services to illustrate the above command.

Here you can see there are two services in the ballerina file. If you want to only document your `/hello` service you can use the command this way.

bal openapi -i petstore.bal --service /hello

If you don’t mention any service in the command it will generate two yaml contracts for each service in the file.

If you wish to take your API blueprint in JSON format, here we provide ‘- -json’ option to make your contract in JSON.

bal openapi -i <ballerina-file-path> --json

You can refer ballerina to openapi example and ballerina openapi tooling guide for more details 😊.

In a summary, It concludes that there is no matter you developer willing to take the approach Code-First or Desing First, In the Ballerina, offers you to achieve these two approaches as you wish.

Hope you may have some sunny idea about the Ballerina OpenAPI CLI Tool and its main usage for addressing the API approaches. And wish you developer use the Ballerina OpenAPI tool for your coding and enjoy it. Feel free to add your experience, suggestions and issues you encountered while using this here. Appreciate it if you guys share your experience with the ballerina 😃.

No one cares if you can’t dance well. Just get up and dance with the ballerina. Don’t worry, Ballerina OpenAPI Tool there for you to assist movement confidently. Thank you all, Happy reading 😃! Cheers !!

Reference :

Ballerina

Ballerina

Design First or Code First: What's the Best Approach to API Development?