API-First With Swagger
Learn about what API First design means and how to define and implement an API using Swagger, which is based on the OpenAPI specification.
Join the DZone community and get the full member experience.Join For Free
With the birth of new channels and interconnected devices (web, mobile, IoT...) the use of RESTful APIs has become fundamental, and the API First Design can be a winning strategy.
The three basic principles of API First are:
- The API comes before the user interface. Before you develop your web application, mobile, IoT, etc, you'll need to define your APIs, and then work on the channels that will use them.
- The API comes before its implementation. By using tools such as Swagger to define and describe interfaces, you are generating discussions with the customer, user story and, mocking the APIs, also a user interface.
- The API must be described or self-descriptive. API documentation is an indispensable requirement for making it usable by humans.
This post will define and implement an API using Swagger.
Design the API
Generate the Mock Server
The second step is to create a mock server so that the API consumers can start integrating it. This operation allows you to work in parallel and receive feedback before you begin the implementation.
The mock server can be created directly by using the online editor and choosing your preferred technology:
Another way is using the cloud service Swaggerhub.
Generate the API Client
Another interesting feature provided by the editor is to create the client stub by choosing from different languages:
Below are some of the supported technologies: ActionScript, Ada, Apex, Bash, C# (.net 2.0, 4.0 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Eiffel, Go, Groovy, Haskell, Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Swift (2.x, 3.x, 4.x), and Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node).
Develop the Implementation
The last step is to develop the business logic. Just as we previously created the mock server, we create the implementation skeleton choosing the technology we will use for the deployment.
The Swagger codegen supports many different technologies: C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell, Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework), PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), and Scala (Finch, Scalatra).
Also, if you use Spring Boot, you can use springfox to integrate the documentation directly into the source code and generate the human-readable version in a dynamic way.
Nowadays, many companies are oriented towards the architecture of microservices, and the API-First design is well-matched with this trend allowing parallel development, with the agile teams.
The second part of this article is “API-First With Jhipster” and is a work in progress.
Opinions expressed by DZone contributors are their own.