API Design Principle

API Design Principle

In this article, I will only talk about WEB API in the microservice scenario, which is usually implemented by RESTFUL, RPC, etc.

Although API has more various definitions in a different scenario, in this blog, I will only talk about WEB API in micro-service scenario, which is usually implemented by RESTFUL, RPC, etc. API represents a capability of an instance of micro-service, hence the format of transition (like XML, JSON) has little impact in the design APIs

However, API design is crucial in the design of micro-service representing the method of communication between services and impacts the integration of services. Generally, a good API design should meet below 2 requirement

  • Platform Independency. Each client can consume API without knowing how it is implemented. API should follow standard protocol and message format to provide service. Transition protocol and format should NOT invade the business logic, which means system should be able to support different transition protocol and message format. 
  • System Reliability. In the circumstance that API has been delivered and non-API version changes, API should be responsible to API contract, no any changes which might cause destructive data. When API needs tremendous update, the version update should reserve timeframe for older version. 

In practice, API design is not an easy effort. Meanwhile, it is also difficult to evaluate the design. From system design and consumer perspective, here we list some simple design principle. 

*Use a Proven RESTful API *

RESTful style API design has some nature advantage, for example, by using HTTP to reduce the coupling of clients and has very good openness. So more and more developers use RESTful style API. But RESTful is only an design idea rather than a principle due to lacking of constraints. 

Hence, when we design RESTful API, we should refer to maturity model of RESTful. 

MATURITY GRADEEXPLANATIONEXAMPLELevel 0Define a root API to finish all actionsPOST /?action=changePasswordLevel 1Create isolated resource address and API scopePOST /user?action=updateLevel 2Use HTTP verb to define the action for resourceGET /users/001Level 3Use API HATEOAS (Hypermedia as the Engine of Application State) to provide information dynamically"links": {

      "deposit": "/accounts/12345/deposit",

      "withdraw": "/accounts/12345/withdraw",

      "transfer": "/accounts/12345/transfer",

      "close": "/accounts/12345/close"


According to scenario, we should choose suitable maturity grade of model.

integration api rest api design restful api design and development

Bootstrap 5 Complete Course with Examples

Bootstrap 5 Tutorial - Bootstrap 5 Crash Course for Beginners

Nest.JS Tutorial for Beginners

Hello Vue 3: A First Look at Vue 3 and the Composition API

Building a simple Applications with Vue 3

Deno Crash Course: Explore Deno and Create a full REST API with Deno

How to Build a Real-time Chat App with Deno and WebSockets

Convert HTML to Markdown Online

HTML entity encoder decoder Online

RESTful API Design Driven Approach

In this tutorial, you will learn the fundamentals of RESTful API design by applying REST principles and best practices. In additon, learn how to define resources, methods, requests, and responses.

What is REST API? An Overview | Liquid Web

What is REST? The REST acronym is defined as a “REpresentational State Transfer” and is designed to take advantage of existing HTTP protocols when used

A Simple Guide to API Development Tools

APIs can be as simple as 1 endpoint for use by 100s of users or as complex as the AWS APIs with 1000s of endpoints and 100s of thousands of users. Building them can mean spending a couple of hours using a low-code platform or months of work using a multitude of tools. Hosting them can be as simple as using one platform that does everything we need or as complex as setting up and managing ingress control, security, caching, failover, metrics, scaling.

API Integration Practices and Patterns

From on-prem-to-cloud integrations to custom application-to-cloud integrations, the questions are the same: What is the integration experience you need to offer and who will own it?

A Simple Guide to Planning API Roadmaps

APIs - the current “big thing” - offer the opportunity for modern organizations to unlock new and lucrative business models. The article below covers some tips on how to spin the API flywheel and leverage its possibilities.