Designing a REST API — What Is a Code-First Approach?

Designing a great REST API is important to have great microservices. The Code-First approach focuses on generating the contract from code. Is it the best possible approach?

You Will Learn

  • What is the Code-First approach to designing a REST API?
  • What are advantages of the Code-First approach?
  • What are disadvantages of the Code-First approach?
  • When do you adopt the Code-First approach?

REST API

This is the fourth article in a series of articles on REST APIs:

What Is Code First?

Whenever you develop a service, such as a REST API or a SOAP API, there are two approaches you could choose from:

  • Code First, and generate the contract out of the code
  • Contract First, and develop the code based on the contract

Let's start with a quick example for Code First.

Spring Boot Code First REST API Example

We are developing a RESTful web service by making use of the Spring Boot Framework to generate the API. For example, in the retrieveAllUsers() API, we expose the "/users" URI and return all the user resources by calling a service method. when we hit this URL, we get these users returned:

Screenshot of code

In a similar manner, there are other service methods defined, each with their own URI. What we are doing with this example is taking the code and generating documentation from it. That documentation lists out how a user can use the service. For this, we use a documentation format called Swagger:

Screenshot of a Swagger page

Swagger enables us to generate documentation from the code. For example, the following is what Swagger generates for a request to retrieve all users:

Screenshot of User Resource page

It lists out the kind of response message we get and the response status accompanying it as well. You can even call that service from Swagger, leading to:

Screenshot of code

You can also send a POST request to "/users":

Screenshot of code

Swagger tells us how to structure the request message and specify the individual field formats inside. It will also tell you the type of response you get back, along with the response code.

What Swagger generates out of the code is called a contract.

Advantages of Code First

The advantages of this approach are mainly:

  • Low-effort contracts: Generating the contract does not require any additional effort. It is just a by-product of the service development, as it can be automatically generated from the code
  • Contract, code in-sync: As the contract is generated from the code, the two always in sync with each other

Disadvantages of Code First

The disadvantages of this approach are as follows:

No Parallel Development

The service producer and the service consumers cannot be developed in parallel. First, the service needs to be developed, then the contract is generated, and only after that, consumer code can be written to adhere to the contract. Without understanding the contract, a consumer cannot be developed.

No Target for Teams

As the contract cannot be known before the service is developed, there is no target for the various stakeholders in development. Hence, there is every chance that directions go wayward, and unnecessary changes are made, leading to wastage of effort.

No Cross-Platform Compatibility

In some older frameworks, it is not that easy to generate the contract from the code. As a result, it is quite common for the contracts generated not being compatible across platforms.

Comments

Post a Comment

Please Share Your Views

Popular posts from this blog

SSO — WSO2 API Manager and Keycloak Identity Manager

Image
In this article, we are going to see how to implement Single Sign-On (SSO) for WSO2 API Manager using Keycloak as a Federated Identity Provider. Also, we'll choose a deep-dive showing how debugging works with the WSO2 API Manager code to see what happens inside when it's configured with a third-party identity provider (i.e Keycloak in this example). High-Level Architecture This is what we are going to do in this tutorial. High-level architecture Software Needed Following softwares will be needed: WSO2 API Manager (2.6.0) Keycloak (6.0.1) Note : We aren’t getting to use WSO2 Identity Server as a middleman for this tutorial. The article is predicated on pure WSO2 API Manager 2.6.0 (all in one). Before We Start The tutorial will be divided into two parts. In the first part, I will explain how to install and configure Keycloak. In the second part, we will see how to install and configure the WSO2 API Manager. Before we start, let's modify the  /etc/hosts  file
Read more

Single Value Decomposition in Data Science

Image
Overview Singular Value Decomposition (SVD) is a common dimensionality reduction technique in data science We will discuss 5 must-know applications of SVD here and understand their role in data science We will also see three different ways of implementing SVD in Python   Introduction “Another day has passed, and I still haven’t used  y = mx + b. “ Sounds familiar? I often hear my school and college acquaintances complain that the algebra equations they spent so much time on are essentially useless in the real world. Well – I can assure you that’s simply not true. Especially if you want to carve out a career in data science. Linear algebra bridges the gap between theory and practical implementation of concepts. A healthy understanding of linear algebra opens doors to  machine learning  algorithms we thought were impossible to understand. And one such use of linear algebra is in Singular Value Decomposition (SVD) for dimensionality reduction. You must have come across SVD a lot in data s
Read more

Video Analysis: Creating Highlights Using Python

Image
Overview Build your own highlights package in Python using a simple approach That’s right – learn how automatic highlight generation works without using machine learning or deep learning! We will implement our own approach to automatic highlight generation using a full-length cricket match   Your Subconscious Mind Receives Each And Every Thought That You Have and Absolutely Accepts It As The Truth, Feeding it back into your Daily Reality. Introduction I’m a huge cricket fan. I’ve been hooked to the game since I can remember and it still fuels my day-to-day routine. I’m sure a lot of you reading this will be nodding your head! But ever since I started working full-time, keeping up with all the matches has been a tough nut to crack. I can only catch fleeting finishes to matches rather than the whole package. Or I have to follow along with text commentary – either way, it leaves me wanting more. So the data scientist in me decided to do something about this
Read more