Can we just generate the API? A study of the alternatives

By Sadulaeva Teona (trsadulaeva@edu.hse.ru)

API, or Application Programming Interface, is the system that allows different software and systems to communicate and interact with each other. It is crucial for any project to construct a simple yet sufficient system, so that working developers could expand said system without breaking its initial parts.

The process of creating APIs can be very tiring and time-consuming. It requires a thorough understanding of the underlying system. In addition to the time and resources required for development of it, manually created APIs generally consist of a bunch of hidden bugs and errors. This is why AI-driven API generation takes place. Let's review a few main approaches[1].

Tools and frameworks can analyze existing code, such as classes, functions, and data structures, and generate an API based on that analysis. This approach is commonly used in frameworks like Swagger, that can generate API documentation and client libraries based on annotated code.

For example, Swagger is focused on providing a comprehensive set of tools for API design, development, and documentation, with an emphasis on intuitive and interactive documentation. It also provides a variety of open source tools for APIs:

* Swagger Editor. Enables developers to write documentation for, design and describe new APIs as well as edit existing ones. The browser-based editor visually renders OpenAPI specifications, handles errors and provides real-time feedback. * Swagger Codegen. Gives developers the ability to generate client library code and SDKs for different platforms. * Swagger User Interface. A fully customizable tool that helps engineers generate documentation for various platforms. It can be hosted in any environment. * Swagger Inspector. A testing tool for API documentation. APIs can be easily validated without limits and results are automatically saved and accessed in the cloud.

Instead of analyzing existing code, APIs can be generated based on specifications or descriptions. For example, OpenAPI allows developers to define APIs using a specification language (usually in YAML or JSON format), and then generate the API code, documentation, and client libraries from that specification. Compared with Swagger, OpenAPI is completely language-agnostic[5] and it shifted its primary focus to provide a standardized format for describing RESTful APIs comprehensively while retaining documentation capabilities from Swagger.

There are three primary areas in every OpenAPI document:

* Endpoints (paths appended to the server URL) and the HTTP methods they support. For each method, any parameters that may or must be included in the request and the response formats for the possible HTTP response codes are specified. * Reusable components that can be used across multiple endpoints in the API, such as common request parameters and response formats. * Meta information, including the title, version, and description of the API, authentication method, and location of the API servers.

OpenAPIs lifecycle assumes an API-first design approach, where the main document is created upfront and code is written to create the implementation of it. There is, of course, the “code-first” approach, when the implementation is created and usually annotated so an OpenAPI document can be generated.

Taking the API first approach means having the design detailed in an OpenAPI document is critical to your implementation. The OAS (OpenAPI System) has a rich tooling ecosystem and using the OpenAPI document to generate server-side code is a common approach to automating the creation of controller classes. This speeds up the delivery of the implementation and helps ensure the interface design and the implementation are closely-matched.

Some low-code development platforms provide visual interfaces that enable developers to define APIs by configuring components and defining data models. These platforms abstract away much of the code implementation and generate the API infrastructure automatically[4]. It's a perfect choice for people that are not very keen on developing something on their own and they're willing to let a computer do their work for them, sacrificing possible optimization and creative approaches in the process. In my opinion this is the least effective way of generating APIs as it will be useless as soon as the platform malfunctions, leaving an angry client with not working product or with a half of it locked behind a paywall.

In conclusion, by automating the API creation process, developers can focus more on the core business logic and functionality of their applications. Moreover, testing of generated APIs is much easier thanks to the extensive documentation[3]. Choosing between different approach, i'd lean on api generation based on an existing code base. That avoids the stress of manually rewriting chunks of code and documentation that won't work with generated API.

1. API management tools [Electronic resource] Access mode: https://www.g2.com/categories/api-management?utf8=%E2%9C%93&selected_view=trending&segment=all#grid (Accessed: Dec 23, 2023). 2. Programming language benchmark [Electronic resource] Access mode: https://benchmarksgame-team.pages.debian.net/benchmarksgame/index.html (Accessed: Dec 23, 2023).

3. Introduction to API testing in Katalon Studio [Electronic resource] Access mode: https://docs.katalon.com/docs/create-tests/introduction-to-test-creation/introduction-to-api-testing-in-katalon-studio (Accessed: Dec 23, 2023). 4. Guide to API-first [Electronic resource] Access mode: https://www.postman.com/api-first/ (Accessed: Dec 23, 2023).

5. Best API Management Tools [Electronic resource] Access mode: https://www.g2.com/categories/api-management (Accessed: Dec 24, 2023).