API 規格(理解範圍/學習&確認撰寫規格)

[godmmt]

API 規格

認識理解 API 查找相關資料文件

---

參考資料： 《精通 API 架構》

預計參考網路文章：

• [x] 淺談 API 與 RESTful API
• [x] Fetch API 到底是 ESMAScript6 還是 Web APIs?

[godmmt]

API 簡介｜《精通 API 架構》導論

在軟體架構領域，有一些術語難以定義。就像 API，也就是 application programing interface（應用程式介面）。這個概念最早出現在非常久遠的 80 年前。已經存在很長時間的術語最終會被過度使用，並且在不同的問題空間有多種含義。我們認為 API 代表的是：

• API 代表底層實作的一個抽象層（abstraction）。
• 一個 API 由一個引入型別（types）的規格（specification）來表示。開發人員可以理解這些規格，並使用工具生成多種語言的程式碼來實作 API 消費者（消耗 API 的軟體）。
• API 定義了語意（semantics）或行為，以有效地為“資訊的交換”建立模型。
• 有效的 API 設計能夠擴充到客戶或第三方以進行業務整合。

廣義上來講，API 可以分為兩大類，取決於 API 的呼叫是在行程內（in process）還是在行程外（out of process）。 這裡的行程是指作業系統（OS）的行程。

舉例來說，從一個類別到另一個類別的 Java 方法調用（method invocation）是行程內的 API 調用，因爲該呼叫是由進行呼叫的同一行程來處理的。 一個 .NET 應用程式使用 HTTP 程式庫呼叫外部的類 REST API 則是行程外的 API 調用，因爲該呼叫是由一個額外的外部行程所處理，而非由進行呼叫的行程處理。 行程外的 API 呼叫將涉及穿越網路的資料，那可能是區域網路、虛擬私有雲（virtual private cloud，VPC）網路、或網際網路（internet）。

[godmmt]

相關名詞解釋｜ChatGPT

• "greenfield technology" means?

  "Greenfield technology" refers to the development or deployment of new systems, projects, or technology in an environment where there is little to no existing infrastructure or legacy systems. The term is often used in contrast to "brownfield," which refers to projects or systems built upon existing infrastructure or systems.

  In the context of software development or technology projects, a greenfield project starts with a clean slate, allowing developers to create and implement solutions without the constraints or limitations imposed by pre-existing systems. This approach is common when there is a need for innovation, a departure from outdated technologies, or the creation of a completely new system.

  Greenfield projects offer the advantage of flexibility and the ability to leverage the latest technologies and best practices. Developers have the freedom to design and implement solutions without being bound by the constraints of legacy systems, making it easier to adopt modern approaches and architectures.

  On the other hand, greenfield projects may also pose challenges, such as the need to establish a new infrastructure from scratch and potential uncertainties in terms of requirements and project scope.

  In summary, "greenfield technology" refers to the development of new technology projects in a fresh and unconstrained environment, unburdened by existing systems or infrastructure.

  "Greenfield technology"（綠地技術）指的是在幾乎沒有現有基礎設施或遺留系統的環境中開發、部署新系統、專案或技術。這個術語通常與「brownfield」相對，後者指的是在現有基礎設施或系統之上構建的專案或系統。

  在軟體開發或技術專案的背景下，綠地專案是從零開始的，允許開發人員在沒有受現有系統約束的情況下創建和實施解決方案。這種方法在需要創新、離開過時技術或創建全新系統的情況下很常見。

  綠地專案具有靈活性的優勢，可以利用最新的技術和最佳實踐。開發人員可以在不受遺留系統約束的情況下設計和實施解決方案，更容易採用現代方法和架構。

  另一方面，綠地專案可能也會面臨挑戰，比如需要從頭開始建立新的基礎設施，以及在需求和專案範圍方面可能存在的不確定性。

  總而言之，「綠地技術」指的是在一個新鮮且不受現有系統或基礎設施約束的環境中開發新技術專案。

---

• "service-oriented architecture" means?

  "Service-Oriented Architecture" (SOA) is an architectural style that structures software applications as a collection of loosely coupled services. These services can be thought of as independent, self-contained units of functionality that communicate with each other over a network. The goal of SOA is to enable the creation of flexible and scalable software systems by promoting reusability and interoperability among services.

  Key features of Service-Oriented Architecture include:

  1. Services: Services in SOA are modular units of functionality that perform specific tasks. Each service is designed to be independent, with well-defined interfaces for communication.
  2. Loose Coupling: Services in an SOA are loosely coupled, meaning that they operate independently of each other. Changes to one service do not necessarily affect other services, promoting flexibility and ease of maintenance.
  3. Interoperability: SOA promotes interoperability, allowing services to be developed in different programming languages and run on different platforms. This flexibility enables organizations to use a mix of technologies.
  4. Reusability: Services can be reused across different applications and projects, reducing development time and promoting consistency. This reusability is a key aspect of the efficiency gains expected from SOA.
  5. Discoverability: SOA often includes mechanisms for discovering and invoking services dynamically. This allows applications to find and use services as needed.
  6. Scalability: SOA architectures can be designed to be scalable, allowing organizations to adapt and expand their systems as needed by adding or modifying services.
  7. Abstraction: Services abstract the underlying implementation details, providing a level of abstraction that makes it easier to understand and use the functionality they offer.

  SOA is commonly used in enterprise-level applications where there is a need for flexibility, scalability, and the ability to integrate diverse systems and technologies.

  In summary, Service-Oriented Architecture is an approach to software design and development that structures applications as a collection of loosely coupled and reusable services, promoting flexibility, scalability, and interoperability.

  "Service-Oriented Architecture"（服務導向架構，簡稱 SOA）是一種將軟體應用程式結構化為一組鬆散耦合服務的架構風格。這些服務可以被視為獨立的、自包含的功能單元，它們通過網路相互通信。SOA 的目標是通過促進服務之間的可重用性和互操作性，實現靈活且可擴展的軟體系統。

  Service-Oriented Architecture 的主要特點包括：

  1. 服務： SOA 中的服務是執行特定任務的模組化功能單元。每個服務都被設計成獨立的，具有明確定義的通信接口。
  2. 鬆散耦合： SOA 中的服務是鬆散耦合的，這意味著它們獨立運作。對一個服務的更改不一定會影響其他服務，促進靈活性和易於維護。
  3. 互操作性： SOA 促進互操作性，允許使用不同編程語言並在不同平台上運行的服務。這種靈活性使組織能夠使用各種技術。
  4. 可重用性： 服務可以在不同應用程式和專案中進行重用，減少開發時間並促進一致性。這種可重用性是從 SOA 中期望的效率提升的關鍵方面。
  5. 可發現性： SOA 通常包括動態發現和調用服務的機制。這使應用程式能夠根據需要找到並使用服務。
  6. 可擴展性： SOA 架構可以設計成可擴展的，使組織可以通過添加或修改服務來適應和擴展其系統。
  7. 抽象化： 服務抽象出底層實現細節，提供了一個層次的抽象，使得更容易理解和使用其提供的功能。

  SOA 常常應用於需要靈活性、可擴展性以及整合多樣系統和技術的企業級應用程式。

  總而言之，服務導向架構是一種軟體設計和開發的方法，將應用程式結構化為一組鬆散耦合和可重用的服務，促進靈活性、可擴展性和互操作性。

---

• SaaS ?

  "SaaS" stands for "Software as a Service." It is a cloud computing service model where software applications are provided over the internet on a subscription basis. Instead of users installing and maintaining the software on their local devices or servers, they access and use the software through a web browser.

  Key characteristics of SaaS include:

  1. Accessibility: SaaS applications are accessible from any device with an internet connection and a web browser. Users can access the software from different locations and devices without the need for installation.
  2. Subscription-Based: SaaS is typically offered on a subscription basis, where users pay a recurring fee to access the software. This subscription model often includes maintenance, updates, and support services.
  3. Centralized Management: The software is centrally hosted and managed by the SaaS provider. This eliminates the need for users to handle tasks such as software maintenance, updates, and security.
  4. Automatic Updates: SaaS providers handle updates and patches, ensuring that users always have access to the latest features and security improvements without needing to perform manual installations.
  5. Scalability: SaaS solutions are often scalable, allowing users to adjust their subscription plans based on their needs. This makes it easy for businesses to scale up or down as their requirements change.
  6. Multi-Tenancy: SaaS applications are typically designed to serve multiple customers (tenants) on the same infrastructure. This multi-tenancy model allows for cost efficiency and shared resources.
  7. Examples: Common examples of SaaS applications include customer relationship management (CRM) software (e.g., Salesforce), office productivity suites (e.g., Google Workspace, Microsoft 365), and collaboration tools (e.g., Slack).

  SaaS has become a popular delivery model for various types of software, providing users with the flexibility to use applications without the burden of installation, maintenance, and infrastructure management.

  "SaaS" 的全名是「軟體即服務」。它是一種雲端運算的服務模式，軟體應用程式以訂閱方式透過網際網路提供。

  使用者無需在本地設備或伺服器上安裝和維護軟體，而是透過網頁瀏覽器存取和使用軟體。

  SaaS 的主要特點包括：

  1. 可存取性： SaaS 應用程式可從任何具有網際網路連線和網頁瀏覽器的設備存取。使用者無需安裝，可在不同地點和設備上使用軟體。
  2. 訂閱制： SaaS 通常以訂閱方式提供，使用者支付定期費用以存取軟體。這種訂閱模式通常包含維護、更新和支援服務。
  3. 中央管理： 該軟體由 SaaS 提供者進行中央託管和管理。這消除了使用者處理軟體維護、更新和安全性等任務的需求。
  4. 自動更新： SaaS 提供者處理更新和修補程式，確保使用者始終能夠存取最新功能和安全改進，而不需要進行手動安裝。
  5. 可擴展性： SaaS 解決方案通常是可擴展的，允許使用者根據需求調整其訂閱計劃。這使得企業能夠根據其需求隨時擴大或縮小。
  6. 多租戶： SaaS 應用程式通常設計為在相同基礎架構上服務多個客戶（租戶）。這種多租戶模式實現了成本效益和共享資源。
  7. 例子： SaaS 應用程式的常見例子包括客戶關係管理（CRM）軟體（例如 Salesforce）、辦公生產力套件（例如 Google Workspace、Microsoft 365）和協作工具（例如 Slack）。

  SaaS 已成為各種軟體的流行交付模式，為使用者提供使用應用程式的靈活性，而無需擔心安裝、維護和基礎架構管理的負擔。

---

• “service mesh” means?

  A "service mesh" is a dedicated infrastructure layer that facilitates communication, management, and monitoring between microservices in a distributed application. Microservices architecture involves breaking down an application into smaller, independently deployable services that work together to fulfill the overall application's functionality.

  Key aspects of a service mesh include:

  1. Communication: Service meshes provide a standardized way for microservices to communicate with each other. This often includes handling tasks such as service discovery, load balancing, and encryption.
  2. Observability: Service meshes offer tools for monitoring and observing the behavior of microservices. This includes collecting and analyzing metrics, logs, and traces to gain insights into the performance and health of the entire system.
  3. Security: Service meshes can enhance the security of microservices communication by handling tasks such as authentication, authorization, and encryption. They help enforce security policies consistently across all microservices.
  4. Traffic Management: Service meshes enable control over the flow of traffic between microservices. This includes capabilities like traffic shaping, canary releases, and routing based on various criteria.
  5. Resilience: Service meshes contribute to the overall resilience of a distributed system by implementing features like circuit breaking and retry mechanisms. These help mitigate the impact of failures in one part of the system on other parts.
  6. Decentralized Control: Service meshes often operate with a decentralized control plane. This means that individual microservices can make decisions locally based on policies set by the service mesh, reducing the need for centralized coordination.

  Popular service mesh implementations include Istio, Linkerd, and Envoy. These tools provide a way to manage the complexity of microservices interactions, offering a set of features that enhance reliability, security, and observability in a distributed application.

  "Service mesh"（服務網格）是一個專用的基礎架構層，促進分布式應用中微服務之間的通信、管理和監控。微服務架構涉及將應用程序拆分為更小、獨立可部署的服務，這些服務共同工作以實現整體應用程序的功能。

  服務網格的主要方面包括：

  1. 通信： 服務網格提供了微服務之間標準化的通信方式。這通常包括處理諸如服務發現、負載平衡和加密等任務。
  2. 可觀察性： 服務網格提供了監控和觀察微服務行為的工具。這包括收集和分析指標、日誌和跟踪，以獲得對整個系統性能和健康狀態的見解。
  3. 安全性： 服務網格可以增強微服務通信的安全性，處理身份驗證、授權和加密等任務。它有助於在所有微服務之間一致實施安全政策。
  4. 流量管理： 服務網格實現對微服務之間流量的控制。這包括流量整形、金絲雀版本和基於各種標準的路由等功能。
  5. 彈性： 服務網格通過實施斷路器和重試機制等功能，有助於提高分佈式系統的整體彈性。這有助於減輕系統某一部分的故障對其他部分的影響。
  6. 去中心化控制： 服務網格通常使用去中心化的控制平面操作。這意味著個別微服務可以基於服務網格設定的策略進行本地決策，減少了集中協調的需要。

  流行的服務網格實現包括 Istio、Linkerd 和 Envoy。這些工具提供了一種管理微服務交互複雜性的方式，提供一組功能，增強了分布式應用程序的可靠性、安全性和可觀察性。

---

• incremental value

  "Incremental value" refers to the additional worth, benefit, or improvement gained by making a small, gradual, or incremental change or addition to a product, service, process, or project. It contrasts with radical or significant changes, emphasizing a step-by-step approach to enhancement.

  Key points about incremental value include:

  1. Small Changes: Incremental value is often achieved through a series of small changes or additions over time rather than through a single large modification.
  2. Continuous Improvement: It is closely tied to the concept of continuous improvement, where ongoing adjustments are made to enhance efficiency, functionality, or other aspects of a product or process.
  3. Reduced Risk: Incremental changes are generally perceived as lower risk compared to large, transformative changes. They allow for testing and validation at each step before committing to more extensive modifications.
  4. Iterative Process: Achieving incremental value is often an iterative process, involving cycles of improvement, assessment, and further refinement based on feedback and outcomes.
  5. Agile Development: The idea of incremental value aligns with agile development methodologies, which emphasize delivering value in small, manageable increments rather than waiting for a complete product.
  6. Flexibility: Incremental approaches provide flexibility in adapting to changing requirements or responding to feedback from users and stakeholders.
  7. Measurable Impact: Each increment contributes to measurable improvements, allowing stakeholders to assess the impact of the changes and make data-driven decisions.

  Overall, the concept of incremental value recognizes the value of making continuous, manageable improvements to achieve long-term goals, fostering adaptability and responsiveness in the face of evolving needs or circumstances.

  "Incremental value"（漸進價值）指的是通過對產品、服務、流程或項目進行小規模、逐步或增量改變或增加而獲得的額外價值、利益或改進。這與激進或顯著的變化形成對比，強調了對增強的漸進式方法。

  有關漸進價值的關鍵點包括：

  1. 小改變： 通常通過一系列小規模的變更或逐步增加來實現漸進價值，而不是通過一次性的大修改。
  2. 持續改進： 它與持續改進的概念密切相關，即對產品或流程進行持續的調整以提高效率、功能或其他方面。
  3. 降低風險： 漸進變更通常被認為比大規模、轉型性的變更風險較小。它允許在採取更廣泛修改之前在每個步驟上進行測試和驗證。
  4. 迭代過程： 實現漸進價值通常是一個迭代的過程，涉及改進、評估和根據反饋和結果進一步的精煉。
  5. 敏捷開發： 漸進價值的概念與敏捷開發方法融為一體，敏捷開發強調在小而可管理的增量中交付價值，而不是等待完整的產品。
  6. 靈活性： 漸進方法提供了適應不斷變化的需求或應對用戶和利益相關者的反饋的靈活性。
  7. 可測量影響： 每個增量都有助於可測量的改進，讓利益相關者評估變更的影響並做出基於數據的決策。

  總之，漸進價值的概念認識到，通過進行持續、可管理的改進來實現長期目標的價值，並在面對不斷變化的需求或情勢時培養適應性和靈活性。

---

• REST API ?

  REST API stands for "Representational State Transfer Application Programming Interface." It is an architectural style for designing networked applications. REST is not a protocol but a set of principles or constraints that, when applied to web services, create what is known as RESTful APIs.

  Key principles of REST include:

  1. Statelessness: Each request from a client to a server must contain all the information needed to understand and process the request. The server should not store any information about the client's state between requests.
  2. Client-Server Architecture: The client and server are separate entities that communicate over a network. The client is responsible for the user interface and user experience, while the server is responsible for processing requests and managing resources.
  3. Uniform Interface: RESTful APIs should have a uniform and consistent interface, which simplifies the architecture and allows for a standardized way of interacting with the services. This is achieved through a set of constraints, including resource identification through URIs, resource manipulation through representations, and self-descriptive messages.
  4. Resource-Based: Resources, which can be data or services, are identified by URIs (Uniform Resource Identifiers). Clients interact with resources through the standard HTTP methods like GET, POST, PUT, and DELETE.
  5. Stateless Communication: Communication between the client and server is stateless, meaning that each request from a client contains all the information needed to understand and process the request. The server does not store information about the client's state between requests.
  6. Representation: Resources are represented in a format such as JSON or XML. Clients interact with these representations to perform actions on resources.
  7. Hypermedia as the Engine of Application State (HATEOAS): Clients interact with the application entirely through hypermedia provided dynamically by application servers through the interpretation of hypermedia links.

  RESTful APIs are widely used in web development because of their simplicity, scalability, and ease of integration. They are commonly used to enable communication between different software systems and allow for the creation of modular and scalable applications.

  REST API 的全名是「表徵狀態傳輸應用程式介面」，是一種設計網路應用程式的架構風格。

  REST 不是一個通訊協定，而是一組適用於 Web 服務的原則或約束，應用這些原則可以建立所謂的 RESTful API。

  REST 的主要原則包括：

  1. 無狀態性： 每個從客戶端到伺服器的請求都必須包含處理請求所需的所有資訊。伺服器不應在請求之間存儲有關客戶端狀態的任何資訊。
  2. 客戶端-伺服器架構： 客戶端和伺服器是分開的實體，它們透過網路進行通信。客戶端負責用戶介面和用戶體驗，而伺服器負責處理請求和管理資源。
  3. 統一介面： RESTful API 應具有統一且一致的介面，簡化架構並允許以標準化的方式與服務進行交互。這通過一組約束實現，包括通過 URI 進行資源識別、通過表示進行資源操作以及具有自我描述性的消息。
  4. 基於資源： 資源，可以是資料或服務，由統一資源識別符（URI）識別。客戶端通過標準的 HTTP 方法（如 GET、POST、PUT 和 DELETE）與資源進行交互。
  5. 無狀態通訊： 客戶端和伺服器之間的通訊是無狀態的，這意味著來自客戶端的每個請求都包含了理解和處理該請求所需的所有資訊。伺服器不在請求之間保留有關客戶端狀態的任何資訊。
  6. 資源表示： 資源以 JSON 或 XML 等格式呈現。客戶端通過這些表示與資源執行操作。
  7. 超媒體作為應用狀態的引擎（HATEOAS）： 客戶端完全通過應用伺服器通過超媒體提供的動態資訊進行交互。

  RESTful API 廣泛應用於 Web 開發，因其簡單性、可擴展性和易於整合。它們通常用於實現不同軟體系統之間的通信，並支持創建模塊化和可擴展的應用程式。

[godmmt]

相關名詞解釋｜《精通 API 架構》導論

• 訊務模式 traffic patterns

  在 API 層次，我們使用訊務模式來描述應用程式組之間的資料流。

  就本書而言，我們指的是應用程式和 API 層級的訊務模式。

  • 南北訊務（north-south traffic）： 代表進入一個訊務（infress flow）。（需注意南北向訊務的安全性）

  • 東西訊務（east-west traffic）： 東西訊務可以被認為是一組應用程式內服務對服務（service-to-sevice）式的通訊。 大多數的東西向訊務，特別是當來源是在你更廣泛的基礎設施內之時，都可以在某種程度上被信任。（儘管可以信任訊務的來源，但仍須考慮保護東西向訊務的安全性）

---

• API 基礎設施和訊務模式

  以 API 為基礎的架構中存在兩個關鍵的基礎設施元件（infrastructure components），是控制訊務的關鍵。

  控制和協調訊務通常被描述為訊務管理（traffic management）。

  一般來說：

  • 南北訊務將由 API 閘道控制（API gateways）。→ see chapter 3
  • 東西訊務由 Kubernetes 或服務網格（service mesh）等基礎設施元件處理。→ see chapter 4

[godmmt]

相關名詞解釋｜ChatGPT

• C4 diagrams means?

  C4 diagrams refer to a set of visualizations used for modeling and documenting the architecture of a software system. The "C4" stands for "Context, Containers, Components, and Code," representing different levels of abstraction in depicting the system's architecture.

  Here's a brief overview of each level in C4 diagrams:

  1. Context Diagrams: These provide a high-level view of the system, showing its interactions with external entities or systems. Context diagrams focus on the boundaries of the system and help stakeholders understand how the system interacts with its environment.
  2. Container Diagrams: Container diagrams zoom in on the software system, breaking it down into containers such as web servers, databases, desktop applications, mobile apps, etc. These diagrams illustrate the major containers and their relationships, providing insights into how they interact.
  3. Component Diagrams: Component diagrams dive deeper into the containers, breaking them down into individual components or services. Components represent major pieces of functionality within containers. These diagrams help in understanding the internal structure of containers and how components collaborate.
  4. Code Diagrams: Code diagrams are optional and represent the internal structure of components in more detail, showing classes, interfaces, and their relationships. These diagrams provide a detailed view of the codebase and how components are implemented.

  C4 diagrams are part of the C4 model, which is a framework for visualizing the architecture of software systems. They promote clarity, simplicity, and consistency in communicating complex architectural concepts to different stakeholders, including developers, architects, and non-technical decision-makers. The C4 model is often used in combination with other documentation and methodologies to provide a comprehensive understanding of a software system's architecture.

  C4 圖表是用於建模和記錄軟體系統架構的一套視覺化工具。

  "C4" 代表 "Context（上下文）、Containers（容器）、Components（元件） 和 Code（程式碼）"，分別代表了在呈現系統架構時的不同抽象層次。

  以下是 C4 圖表中的每個層次的簡要概述：

  1. 上下文圖表： 這些提供了系統的高層次視圖，展示其與外部實體或系統的互動。上下文圖表聚焦於系統的邊界，有助於利害關係人理解系統如何與其環境互動。
  2. 容器圖表： 容器圖表放大了軟體系統，將其拆分為容器，如 Web 伺服器、資料庫、桌面應用程式、移動應用程式等。這些圖表說明了主要容器及其關係，提供了有關它們如何互動的洞察。
  3. 元件圖表： 元件圖表更深入容器，將其細分為單個元件或服務。元件代表容器內的主要功能部分。這些圖表有助於理解容器的內部結構以及元件之間的協作方式。
  4. 程式碼圖表： 程式碼圖表是可選的，表示元件的更詳細的內部結構，顯示類別、介面及其關係。這些圖表提供了對程式碼庫的詳細視圖，以及元件是如何實現的。

  C4 圖表是 C4 模型的一部分，該模型是一個用於可視化軟體系統架構的框架。它促進在不同利害關係人（包括開發人員、架構師和非技術決策者）之間傳達複雜架構概念的清晰、簡單和一致的方式。C4 模型通常與其他文件和方法結合使用，以全面理解軟體系統架構。

---

• Architecture Decision Records means?

  Architecture Decision Records (ADRs) are documents used to capture and communicate decisions made regarding a software system's architecture. ADRs serve as a valuable tool for documenting the context, options considered, and reasons behind architectural decisions, providing a historical record that aids in understanding the system's evolution.

  Key components of an Architecture Decision Record typically include:

  1. Title: A concise and descriptive title that summarizes the decision.
  2. Status: Indicates the current status of the decision, such as proposed, accepted, or deprecated.
  3. Context: Describes the circumstances or conditions leading to the decision. This includes any relevant background information, constraints, and concerns.
  4. Decision: Clearly states the chosen architectural decision. This is the central element of the record and should be expressed in a way that is easy to understand.
  5. Options Considered: Lists alternative solutions or options that were evaluated before making the decision. This provides insights into the decision-making process.
  6. Consequences: Outlines the positive and negative impacts of the chosen decision. This includes any trade-offs, risks, and implications for the system.
  7. Rationale: Provides the reasoning behind the decision, explaining why a particular option was chosen over others. This helps future stakeholders understand the thought process behind the decision.
  8. Dependencies: Identifies any dependencies created by the decision, including how it relates to other architectural components or decisions.

  ADRs are particularly useful in the following scenarios:

  • Knowledge Transfer: ADRs serve as a knowledge-sharing tool, helping new team members understand the architectural decisions made in the past.
  • Continuous Documentation: They contribute to the ongoing documentation of the system's architecture, capturing the rationale behind decisions and providing context for future changes.
  • Decision Accountability: ADRs establish accountability by documenting who made the decision and when.
  • Avoiding Repeated Mistakes: They help prevent the repetition of past mistakes by providing insights into the outcomes of previous decisions.

  By maintaining a collection of ADRs, development teams can create a comprehensive record of their architectural choices, fostering transparency and facilitating communication among team members.

  建築決策記錄（ADR）是用於記錄和傳達有關軟體系統架構的決策的文件。

  ADR 被視為一種有價值的工具，用於記錄決策的背景、考慮的選項以及背後的原因，提供了一個有助於理解系統演變的歷史記錄。

  建築決策記錄通常包括以下主要組件：

  1. 標題： 簡潔且描述性的標題，總結了該決策的內容。
  2. 狀態： 表示決策的當前狀態，如提議、已接受或已棄用。
  3. 上下文： 描述導致該決策的情境或條件。這包括任何相關的背景資訊、約束和關注點。
  4. 決策： 清晰陳述所選擇的架構決策。這是記錄的核心元素，應以易於理解的方式表達。
  5. 考慮的選項： 列舉在做出決策之前評估的替代解決方案或選項。這提供了對決策過程的深入了解。
  6. 影響： 概述所選擇決策的正面和負面影響。這包括任何權衡、風險和對系統的影響。
  7. 原因： 提供做出決策的理由，解釋為什麼選擇了特定的選項。這有助於未來的利害關係人了解決策背後的思考過程。
  8. 相依性： 識別由決策創建的任何相依性，包括它與其他建築元件或決策的相關性。

  建築決策記錄特別在以下情況下很有用：

  • 知識轉移： ADR 作為一種知識分享工具，有助於新團隊成員了解過去所做的架構決策。
  • 持續文件化： 它們有助於對系統架構的持續文檔化，記錄決策背後的原因，為未來的更改提供上下文。
  • 決策負責制： ADR 通過記錄誰何時做出了決策，確立了負責制。
  • 避免重複錯誤： 有助於通過提供對先前決策結果的洞察，防止重複過去的錯誤。

  P.S. 在「Architecture Decision Records」（ADRs）的背景下，「concerns」不是指擔憂或焦慮，而是指在做出架構決策時需要考慮的因素、要點或方面。當在一個ADR中記錄「Context」部分時，您會概述影響或促成該決策的關注點。這些關注點可能包括各種因素，如業務需求、性能考慮、可擴展性問題、安全需求、合規性問題、技術限制等。

[godmmt]

相關名詞解釋｜ChatGPT

• How about 'UML'?

  "UML" stands for Unified Modeling Language. It is a standardized, general-purpose modeling language in the field of software engineering. UML provides a set of graphical notations for visualizing, specifying, constructing, and documenting the artifacts of a software-intensive system.

  Key features of UML include:

  1. Unified: UML unifies various modeling notations and approaches, providing a standardized way to visualize and document software systems.
  2. Graphical Notations: UML uses graphical symbols and diagrams to represent different aspects of a system, making it easier for stakeholders to understand complex software designs.
  3. Modeling Elements: UML includes a set of modeling elements, such as classes, objects, use cases, activities, and interactions, that allow developers to represent different aspects of a system's architecture and behavior.
  4. Structural and Behavioral Views: UML supports the creation of both structural and behavioral models. Structural diagrams (like class diagrams) depict the static structure of a system, while behavioral diagrams (like sequence diagrams) illustrate the dynamic aspects.
  5. Standardization: UML is an industry-standard and is maintained by the Object Management Group (OMG). This standardization ensures consistency and compatibility across different software development tools and environments.
  6. Versatility: UML is versatile and can be applied in various stages of the software development life cycle, from initial concept and design to implementation and maintenance.

  Common types of UML diagrams include:

  • Class Diagrams: Represent the static structure of a system, showing classes, attributes, and relationships.
  • Use Case Diagrams: Illustrate the interactions between a system and its external entities or actors.
  • Sequence Diagrams: Display the interactions between objects over time.
  • Activity Diagrams: Describe the dynamic aspects of a system, focusing on workflow and process.
  • State Machine Diagrams: Depict the states and transitions of an object or system.

  UML is widely used in the software development industry as a standard notation for visualizing and communicating system designs among developers, architects, and other stakeholders.

  "UML" 代表統一建模語言。它是軟體工程領域中的標準通用建模語言。UML 提供了一套圖形符號，用於可視化、指定、構建和記錄軟體密集型系統的工件。

  UML 的主要特點包括：

  1. 統一性： UML 統一了各種建模符號和方法，提供了一種標準的方式來可視化和記錄軟體系統。
  2. 圖形符號： UML 使用圖形符號和圖表來表示系統的不同方面，使利害關係人更容易理解複雜的軟體設計。
  3. 建模元素： UML 包括一套建模元素，如類、物件、用例、活動和交互，允許開發人員表示系統架構和行為的不同方面。
  4. 結構和行為視圖： UML 支援結構和行為模型的創建。結構圖（如類圖）描述系統的靜態結構，而行為圖（如序列圖）則說明動態方面。
  5. 標準化： UML 是行業標準，由物件管理小組（Object Management Group，OMG）維護。這種標準化確保了在不同軟體開發工具和環境中的一致性和兼容性。
  6. 多用途性： UML 非常靈活，可應用於軟體開發生命週期的各個階段，從初始概念和設計到實施和維護。

  常見的 UML 圖表類型包括：

  • 類圖： 代表系統的靜態結構，顯示類別、屬性和關係。
  • 用例圖： 說明系統與外部實體或操作者之間的互動。
  • 序列圖： 顯示物件隨時間的互動。
  • 活動圖： 描述系統的動態方面，著重於工作流程和過程。
  • 狀態機圖： 描繪物件或系統的狀態和轉換。

  UML 在軟體開發行業中被廣泛使用，作為開發人員、架構師和其他利害關係人之間可視化和溝通系統設計的標準符號。

---

• self-documenting means ?

  "Self-documenting" refers to the quality of a code or system that is designed in such a way that the code itself serves as documentation. In a self-documenting code, the structure, variable names, and comments within the code are clear and expressive enough to convey the purpose and functionality of the code without the need for external documentation. This approach aims to make the code easily understandable for both the original developer and others who may work on or maintain the code in the future. It contributes to improved readability and reduces the reliance on separate documentation files.

  "Self-documenting" 的意思是代表程式碼或系統的品質，其設計方式使得程式碼本身充當文件。在自我記錄的程式碼中，程式碼的結構、變數名稱和註釋足夠清晰和表達性，可以在不需要外部文件的情況下傳達程式碼的目的和功能。 這種方法旨在使原始開發者和未來可能參與或維護程式碼的其他人更容易理解程式碼。它有助於提高代碼的可讀性，減少對單獨文件的依賴。

[godmmt]

以下內容的資料來源：淺談 API 與 RESTful API

API

• 維基百科

  應用程式介面（英語：Application Programming Interface），縮寫為API，是一種計算介面，它定義多個軟體中介之間的互動，以及可以進行的呼叫（call）或請求（request）的種類，如何進行呼叫或發出請求，應使用的資料格式，應遵循的慣例等。它還可以提供擴充機制，以便使用者可以通過各種方式對現有功能進行不同程度的擴充。一個API可以是完全客製化的，針對某個組件的，也可以是基於行業標準設計的以確保互操作性。通過資訊隱藏，API實現了模組化編程，從而允許使用者實現獨立地使用介面。

• 換個方式形容：

  今天我(使用者)想要看哥吉拉的描述，但是這邊畫家很窮，每一次想看什麼，我都必須提供一張白紙，並附上一張信件的內容 (Request) 描述，舉例來講：畫家你好，我希望可以請你幫忙準備畫一張哥吉拉的畫像。 接下來我們就會請帥氣郵差先生/小姐(網路)幫我們將信件內容交給畫家(伺服器)，接下來畫家就會依據我們信件內容開始準備畫筆並在我們一起寄給他的白紙繪畫上哥吉拉的畫像，最後繪畫完畢之後，畫家會再請郵差將畫好的繪畫一起寄回去給我來觀看。

其實概念就非常雷同，我們今天如果要寫信給朋友，就會請郵差依照我們提供的地址寄送給朋友，然後朋友就會依據信件內容回覆給我們。 我們套入程式的角度來看就像是：使用者(我)、郵差(API)、朋友(主機)

• 簡單而言：

  API 本身是一個你請求它做什麼事情，然後系統會依照你請求的回應給你什麼東西。

RESTful API

簡單來講 RESTful API 是一個 API 設計風格

早期我們在開發 API 的時候可能會是像以下這樣子來命名：

• getUserAll - 取得全部使用者
• getUser/1 - 取得特定使用者
• createUser - 新增使用者
• editUser/1 - 編輯特定使用者
• deleteUser/1 - 刪除特定使用者

看起來是相當直覺沒有錯，但如果是採用 RESTful API 的話，它則會長得像是以下：

• [Get] /users - 取得全部使用者
• [Get] /user/1 - 取得特定使用者
• [Post] /user - 新增使用者
• [Put] /user/1 - 編輯特定使用者
• [Delete] /user/1 - 刪除特定使用者

我們可以看到 RESTful API 風格的設計方式具有以下優勢：

• 簡潔
• 符合 HTTP Methods

除此之外這邊也要注意一下 RESTful API 的一些設計重點：

• 普通的資源會傾向使用復數(加上 s)
  • 如：/users or /courses，但我也有看過使用單數就是了。
• 唯一(單一)資源使用單數
  • 如：/user/1 or /course/1，例如你要編輯單一使用者、單一課程這類就會建議使用單數。
• 命名盡可能都是採用小寫，若要區分的話可以使用 ` or_`
  • 但我個人是比較喜歡使用 `，如/my-course`。
• 盡可能透過該 API 命名就可以知道用途
  • 如果你取名為 /products 但回傳的卻是使用者資料那也很奇怪吧？
  • 請不要隨意命名，如：/abc 這類型無意義的命名。
  • 假設今天是電商產品 API 的話，可以像這樣命名 [Get] /shopping/products。
• 適當的提供 HTTP Code，這一區塊建議可詳見 wiki。
• 盡可能在 API 設計上要考慮到可擴充與彈性
  • 舉例來講，通常我們可能會遇到 API 的升級，所以我自己在命名上就會用 v1、v2 作為差異區分，如：[Get] /v1/shopping/products、[Put] /v1/shopping/product/1。

因此採用 RESTful API 風格設計是為了盡可能統一且可擴充，對於開發者來講也可以透過該 API 很直覺的理解到用途。

[godmmt]

take 8 hrs remain 4 hrs

[godmmt]

主任務：開 API 規格

子任務：

• [x] 1. 認識理解 API 的本質
• [ ] 2. 了解專案內容
  • [x] 安裝開發環境 https://github.com/CAFECA-IO/BAIFA/issues/341
  • [ ] 閱讀：專案規格(?)
  • [ ] 閱讀：專案的開發環境 Know How(?)
  • [x] 確認是否 clone 專案下來看看(?)

---

通常開 API 的流程是：等UI/UX畫面出來後，按照畫面開 API 規格 。

[Luphia]

1. UI/UX 畫面出來就能討論 API 了，不用等畫面刻完

[godmmt]

1. UI/UX 畫面出來就能討論 API 了，不用等畫面刻完

好的，瞭解了，謝謝。

[godmmt]

了解專案內容 卡在安裝開發環境 https://github.com/CAFECA-IO/BAIFA/issues/341 以及

• 閱讀：專案規格(?)
• 閱讀：專案的開發環境 Know How(?)
• 確認是否 clone 專案下來看看(?)

---

主任務更新為：

• [x] List all URLs in BAIFA
• [x] List all APIs for each URLs

remain 8 hrs

[godmmt]

1. List all URLs in BAIFA

   ignore root URL: https://baifa-boy6tsv96-cafeca.vercel.

• [x] app/en/app
• [x] app/en/app/chains
• [x] app/en/app/chains/isun
• [x] app/en/app/chains/isun/block/230676
• [x] app/en/app/chains/btc/address/110029

---

• [x] app/en/app/chains/btc/address/110029/interaction?type=address
• [x] app/en/app/chains/btc/transaction/916841
• [x] app/en/app/chains/btc/contract/311382

---

• [x] app/en/app/currencies
• [x] app/en/app/currencies/btc
• [x] app/en/app/currencies/btc/red-flag

---

• [x] app/en/app/transaction-list?addressId=114007&addressId=110029
• [x] app/en/app/blacklist
• [x] app/en/app/red-flag
• [x] app/en/app/searching-result?search=2300

2. List all APIs for each URLs

check them bellow:

[godmmt]

The way to quickly open the latest deployment

Here:

And go here:

[godmmt]

Page Title (html head title tag) : Home - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app （英文）

1. search 關鍵字提示 API ( request when input content change ) (input)

   • Method=GET
   • service root URL/api/v1/suggestions/:search-input?
   • Path Parameters : search-input

   • Response :

     {
       "suggestions": ["app", "apple", "apple pie", "android", "avocado"]
     }

2. search 回傳搜尋結果 API (request when button is clicked) (button)

   轉跳到下方的 URL，並將 input value 用 params 傳遞 :

   https://baifa-boy6tsv96-cafeca.vercel.app/en/app/searching-result?search=2300

   進入此 URL 後自動打 API :

   • Method=GET
   • service root URL/api/v1/search/:search-input?
   • Path Parameters : search-input

   • Response :

     {
       "success": true,
       "value": [
         {
           "id": 0,
           "name": "Bitcoin",
           "blocks": 2,
           "transactions": 6
         },
         {
           "id": 1,
           "name": "Binance",
           "blocks": 1,
           "transactions": 1
         }
             // ...
       ]
     }

3. 區塊鏈／加密貨幣／黑名單用戶 API

   • Method=GET
   • service root URL/api/v1/home-features
   • 畫面炫染後自動打 API

   • Response :

     {
         {
           "id": 0,
           "name": "Chains",
         ~~~~  "count": 5
         },
         {
           "id": 1,
           "name": "Crypto Currencies",
           "count": 5
         },
         {
           "id": 2,
           "name": "Black List",
           "count": 7
         }
     }

[godmmt]

Page Title (html head title tag) : Chains - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains

1. Explore Blockchains API

   • Method=GET
   • service root URL/api/v1/chains-all
   • 畫面炫染後自動打 API

   • Response :

     {
       "success": true,
       "value": [
         {
           "id": 0,
           "name": "iSunCloud",
           "blocks": 2,
           "transactions": 6
         },
         {
           "id": 1,
           "name": "Ethereum",
           "blocks": 2,
           "transactions": 6
         },
         {
           "id": 2,
           "name": "Bitcoin",
           "blocks": 2,
           "transactions": 6
         },
         {
           "id": 3,
           "name": "Tether",
           "blocks": 4,
           "transactions": 7
         },
         {
           "id": 4,
           "name": "Binance",
           "blocks": 1,
           "transactions": 1
         }
       ]
     }

[godmmt]

Page Title : iSunCloud - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/isun

1. Blocks API

   • Method=GET
   • service root URL/api/v1/isuncloud/blocks?start-date=:startTimestamp&end-date=:endTimestamp
   • Query Parameters : start-date、end-date（startTimestamp變數直接抓當下時間戳記，endTimestamp可以設定成往前幾個天數）

   • Response :

     {
         {
         "id": 230021,
         "date": 1679998900,
         "category": "Blocks",
         "stability_level":"High"
         },
         {
         "id": 230676,
         "date": 1679978920,
         "category": "Blocks",
         "stability_level": "Medium"
         }
         // ...
     }

2. Blocks API query by Date （日曆功能）

   • Method=GET
   • service root URL/api/v1/isuncloud/blocks?start-date=:startTimestamp&end-date=:endTimestamp
   • Query Parameters : start-date、end-date

   • Response :

     {
         {
             "id": 230021,
             "date": 1679998900,
             "category": "Blocks",
             "stability_level":"High"
         },
         // ...
     }

3. Transactions API

   • Method=GET
   • service root URL/api/v1/isuncloud/transations?start-date=:startTimestamp&end-date=:endTimestamp
   • Query Parameters : start-date、end-date（startTimestamp變數直接抓當下時間戳記，endTimestamp可以設定成往前幾個天數）

   • Response :

     {
         {
             "id": 990071,
           "date": 1692342345,
           "category": "Transactions",
           "stste": "success"
             "asset_type":"Crypto Currency"
         },
         {
             "id": 930291,
           "date": 1689352675,
           "category": "Evidence",
           "state": "false",
             "asset_type":"Crypto Currency"
         },
         {
         "id": 930032,
             "date": 1688342795,
             "category": "Transactions",
             "state": "pending"
         "asset_type":"NFT"
         }
         // ...
     }

4. Transactions API query by Date （日曆功能）

   • Method=GET
   • service root URL/api/v1/isuncloud/transations?start-date=:startTimestamp&end-date=:endTimestamp
   • Query Parameters : start-date、end-date

   • Response :

     {
         {
         "id": 990071,
          "date": 1692342345,
          "category": "Transactions",
          "stste": "success"
         "asset_type":"Crypto Currency"
         },
         // ...
     }

[godmmt]

Page Title (html head title tag) : Block 230676 - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/isun/block/230676

前一個URL點選後，將 230676 這個 block id 用params傳至這個URL

1. Block API

   • Method=GET
   • service root URL/api/v1/isuncloud/block/:block-id

   • Response :

     {
       "id": 230021,
       "date": 1679998900,
       "stability_level":"High",
       "management-team":[],
       "content":[{},{},{}],
       "miner_and_reward":{},
       "size": 3523
     }

[godmmt]

• 4 URLs (pages) : used 8 hours
• 10 URLs remaining : need 16 hours

[godmmt]

Page Title (html head title tag) : Home - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app （英文）、 https://baifa-boy6tsv96-cafeca.vercel.app/app （正體中文）、 https://baifa-boy6tsv96-cafeca.vercel.app/cn/app （簡體中文）

畫面：

• 001 Search suggestions API (關鍵字提示)

  • Method=GET
  • service root URL/api/v1/suggestions/:search-input?
  • Path Parameters : search-input
  • Response :

  {
    "suggestions": ["app", "apple", "apple pie", "android", "avocado"]
  }

• 002 Search Result API

  URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/searching-result

  • Method=GET
  • service root URL/api/v1/search-result?search=2300
  • Response :

  {
      {
          "blockId": 230021,
          "createdDate": 1679998900,
          "category": "Block",
          "stabilityLevel":"High"
      },
      {
          "blockId": 230676,
          "createdDate": 1679978920,
          "category": "Block",
          "stabilityLevel": "Medium"
      }
      // ...
  }

• 003 home features API (區塊鏈／加密貨幣／黑名單用戶)

  • 備註：畫面炫染後自動打 API
  • Method=GET
  • service root URL/api/v1/home-features
  • Response :

  {
      {
          "id": 0,
          "name": "Chains",
          "count": 5,
      },
      {
          "id": 1,
          "name": "Crypto Currencies",
          "count": 5,
      },
      {
          "id": 2,
          "name": "Black List",
          "count": 7,
      }
  }

Page Title (html head title tag) : Chains - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains

畫面：

• 004 Chains API

  • 備註：畫面炫染後自動打 API
  • Method=GET
  • service root URL/api/v1/chains-all
  • Response :

  {
    "success": true,
    "value": [
      {
        "chainId": 0,
        "chainName": "iSunCloud",
        "blocks": 2,
        "transactions": 6,
        "category": "Chain"
      },
      {
        "chainId": 1,
        "chainName": "Ethereum",
        "blocks": 2,
        "transactions": 6,
        "category": "Chain"
      },
      {
        "chainId": 2,
        "chainName": "Bitcoin",
        "blocks": 2,
        "transactions": 6,
        "category": "Chain"
      },
      {
        "chainId": 3,
        "chainName": "Tether",
        "blocks": 4,
        "transactions": 7,
        "category": "Chain"
      },
      {
        "chainId": 4,
        "chainName": "Binance",
        "blocks": 1,
        "transactions": 1,
        "category": "Chain"
      }
    ]
  }

Page Title (html head title tag) : iSunCloud - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/isun

畫面 :

• 005 Blocks API :

  • Method=GET
  • service root URL/api/v1/isuncloud/blocks?start_date=:startTimestamp&end_date=:endTimestamp
  • 備註：Query Parameters : start_date、end_date（startTimestamp變數直接抓當下時間戳記，endTimestamp可以設定成往前幾個天數）
  • Response :

  {
      {
          "blockId": 230021,
          "createdDate": 1679998900,
          "category": "Block",
          "stabilityLevel":"High"
      },
      {
          "blockId": 230676,
          "createdDate": 1679978920,
          "category": "Block",
          "stabilityLevel": "Medium"
      }
      // ...
  }

• 006 Blocks API query by Date （日曆功能）

  • Method=GET
  • service root URL/api/v1/isuncloud/blocks?start_date=:startTimestamp&end_date=:endTimestamp
  • 備註：Query Parameters : start_date、end_date
  • Response :

  {
      {
          "blockId": 230021,
          "createdDate": 1679998900,
          "category": "Block",
          "stabilityLevel":"High"
      },
      // ...
  }

• 007 Transactions API

  • Method=GET
  • service root URL/api/v1/isuncloud/transactions?start_date=:startTimestamp&end_date=:endTimestamp
  • 備註：Query Parameters : start_date、end_date（startTimestamp變數直接抓當下時間戳記，endTimestamp可以設定成往前幾個天數）
  • Response :

  {
      {
          "category": "Transaction",
          "transactionId": 930071,
          "transactionTime": 1692342345,
          "belongBlock": 230021,
          "transactionStatus": "success",
          "assetType":"Crypto Currency",
      },
      {
          "category": "Transaction",
          "transactionId": 930291,
          "transactionTime": 1689352675,
          "belongBlock": 230676,
          "transactionStatus": "false",
          "assetType":"Evidence",
      },
      {
          "category": "Transaction",
          "transactionId": 930032,
          "transactionTime": 1688342795,
          "belongBlock": 230021,
          "transactionStatus": "pending",
          "assetType":"NFT",
      }
      // ...
  }

• 008 Transactions API query by Date （日曆功能）

  • Method=GET
  • service root URL/api/v1/isuncloud/transactions?start_date=:startTimestamp&end_date=:endTimestamp
  • 備註：Query Parameters : start_date、end_date
  • Response :

  {
      {
          "category": "Transaction",
          "transactionId": 930071,
          "transactionTime": 1692342345,
          "belongBlock": 230021,
          "transactionStatus": "success",
          "assetType":"Crypto Currency",
      },
      // ...
  }

Page Title (html head title tag) : Block 230676 - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/isun/block/230676

畫面：

• 備註：前一個 URL 點選後，將 230676 這個 block id 用 params 傳至這個 URL

• 009 Block API :

  • Method=GET
  • service root URL/api/v1/isuncloud/block/:block_id
  • Response :

    {
    "blockId": 230676,
    "createdDate": 1679998900,
    "stabilityLevel": "High",
    "managementTeam": ["Linda", "Liam"],
    "transactionsContent": [
    {
      "category": "Transaction",
      "hash": "0x773A74Cd884139069fEc25f56f9537631A62773",
      "transactionId": 916841,
      "assetType": "Evidence",
      "transactionStatus": "Failed",
      "transactionTime": 1698742345,
      "belongBlock": 217328,
      "addressFrom": 115588,
      "addressTo": 311382,
      "evidence": 515482,
      "value": 0,
      "transactionFee": 0.01,
      "transactionFeeUnit": "BLT",
      "flagging": null,
      "privateNote": "This is my private note."
    }
    // ...
    ],
    "miner": 0,
    "reward": 0.01,
    "size": 3523
    }

Page Title (html head title tag) : Transaction List of Block 230676 - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/transaction-list?blockId=230676

畫面：

• 備註：前一個 URL 點選後，將 230676 這個 block id 用 params 傳至此 URL

• 010 Transactions of a block API :

  • Method=GET
  • service root URL/api/v1/isuncloud/transactions?start_date=:startTimestamp&end_date=:endTimestamp&block_id=:blockId
  • 備註：Query Parameters : start_date、end_date、block_id（startTimestamp變數直接抓當下時間戳記，endTimestamp可以設定成往前幾個天數）
  • Response :

  {
      {
          "category": "Transaction",
          "transactionId": 916841,
          "assetType": "Evidence",
          "transactionStatus": "Failed",
          "transactionTime": 1698742345,
      },
      {
          "category": "Transaction",
          "transactionId": 914025,
          "assetType": "Crypto Currency",
          "transactionStatus": "Success",
          "transactionTime": 1698342345,
      },
      {
          "category": "Transaction",
          "transactionId": 930071,
          "assetType": "Crypto Currency",
          "transactionStatus": "Success",
          "transactionTime": 1692342345,
      },
      // ...
  }

Page Title (html head title tag) : Transaction 916841 - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/btc/transaction/916841

• 011 Transaction API

  • Method=GET
  • service root URL/api/v1/isuncloud/transaction/:transactionId?
  • Response :

  {
      {
          "category": "Transaction",
          "transactionId": 916841,
          "transactionTime": 1698742345,
          "assetType": "Evidence",
          "transactionStatus": "Failed",
          "belongBlock": 217328,
          "addressFrom": 115588,
          "addressTo": 311382,
          "evidence": 515482,
          "value": 100,
          "transactionFee": 0.01,
          "flagging": "None",
          "privateNote": "This is a private note."
      },
  }

Currency List - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/currencies

• 012 Currencies API

  • Method=GET
  • service root URL/api/v1/currencies
  • Response :

    {
    {
    "category": "Currency",
    "currencyName": "Bitcoin",
    "redFlag": [
      {
        "category": "Address",
        "addressID": 112840,
        "flagType": "Multiple Transfer",
        "createTime": 1686230832,
      },
      // ...
    ]
    },
    }

Bitcoin - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/currencies/btc

• 013 Currency API

  • Method=GET
  • service root URL/api/v1/currency/:currencyName
  • Response :

  {
    "category": "Currency",
    "currencyName": "Bitcoin",
    "price": 27755.4,
    "volumeIn24Hours": 14867304472,
    "totalAmount": 19388600,
    "totalAmountUnit":"BTC",
    "holders": [
      {
        "category": "Address",
        "addressId": 110029,
        "address": "0x156f9f74C2775D3190693fEc256dd8843A79",
        "SignUpTime": 1667129031,
        "LatestActiveTime": 200,
        "RelatedAddresses": [110132, 114007],
        "InteractedWith": [[110132, 114007],[]],
  
      },
      // ...
    ],
    "totalTransfers": 48010097,
    "redFlag": [
      {
        "category": "Address",
        "addressID": 112840,
        "flagType": "Multiple Transfer",
        "createTime": 1686230832,
      },
      // ...
    ],
  },

Address 110029 - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/btc/address/110029

• 014 Address API

  • Method=GET
  • service root URL/api/v1/address/:addressId
  • Response :

  {
    "category": "Address",
    "addressId": 110029,
    "address": "0x156f9f74C2775D3190693fEc256dd8843A79",
    "signUpTime": 1667129031,
    "LatestActiveTime": 200,
    "RelatedAddresses": [110132, 114007],
    "InteractedWith": [
      [110132, 114007], // addresses
      [] // contracts
    ],
    "redFlag": [
      {
        "category": "Address",
        "addressID": 110029,
        "flagType": "Multiple Withdraw",
        "createTime": 1686230832,
      },
      // ...
    ],
    "balance": 0,
    "totalSent": 0,
    "totalReceived": 0,
    "privateNote": "",
    "reviews": {},
    "transactionHistory": {},
    "blockProducedHistory": {},
  },

[godmmt]

14 APIs : for now total used 16 hours (total: 10 URLs) 5 URLs remaining : need more 4 hours

[godmmt]

更新：

Home - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app

• 001 Search suggestions API (關鍵字提示)

  • Method=GET
  • service root URL/api/v1/suggestions/:searchInput
  • Response :

  {
    "suggestions": ["app", "apple", "apple pie", "android", "avocado"]
  }

• 002 Search Result API

  URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/searching-result

  • Method=GET
  • service root URL/api/v1/search-result?search_input=:searchInput
  • Response :

  [
    {
      "blockId": 230021,
      "createdDate": 1679998900,
      "category": "Block",
      "stabilityLevel": "High"
    },
    {
      "blockId": 230676,
      "createdDate": 1679978920,
      "category": "Block",
      "stabilityLevel": "Medium"
    }
    // ...
  ]

• 003 home features API (區塊鏈／加密貨幣／黑名單用戶)

  • Method=GET
  • service root URL/api/v1/home-features
  • Response :

  [
    {
      "id": 0,
      "name": "Chains",
      "count": 5
    },
    {
      "id": 1,
      "name": "Crypto Currencies",
      "count": 5
    },
    {
      "id": 2,
      "name": "Black List",
      "count": 7
    }
  ]

---

Chains - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains

• 004 Chains API

  • Method=GET
  • service root URL/api/v1/chains-all
  • Response :

  {
    "success": true,
    "value": [
      {
        "chainId": "isun",
        "chainName": "iSunCloud",
        "blocks": 2,
        "transactions": 6,
        "category": "Chain"
      },
      {
        "chainId": "eth",
        "chainName": "Ethereum",
        "blocks": 2,
        "transactions": 6,
        "category": "Chain"
      },
      {
        "chainId": "btc",
        "chainName": "Bitcoin",
        "blocks": 2,
        "transactions": 6,
        "category": "Chain"
      },
      {
        "chainId": "usdt",
        "chainName": "Tether",
        "blocks": 4,
        "transactions": 7,
        "category": "Chain"
      },
      {
        "chainId": "bnb",
        "chainName": "Binance",
        "blocks": 1,
        "transactions": 1,
        "category": "Chain"
      }
    ]
  }

---

iSunCloud - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/isun

• 005 Blocks API :

  • Method=GET
  • service root URL/api/v1/:chainId/blocks?start_date=:startTimestamp&end_date=:endTimestamp
  • 備註：Query Parameters : start_date、end_date（startTimestamp變數直接抓當下時間戳記，endTimestamp可以設定成往前幾個天數）
  • Response :

  [
    {
      "blockId": 230021,
      "createdDate": 1679998900,
      "category": "Block",
      "stabilityLevel": "High"
    },
    {
      "blockId": 230676,
      "createdDate": 1679978920,
      "category": "Block",
      "stabilityLevel": "Medium"
    }
    // ...
  ]

• 006 Blocks API query by Date （日曆功能）

  • Method=GET
  • service root URL/api/v1/:chainId/blocks?start_date=:startTimestamp&end_date=:endTimestamp
  • 備註：Query Parameters : start_date、end_date
  • Response :

  [
    {
      "blockId": 230021,
      "createdDate": 1679998900,
      "category": "Block",
      "stabilityLevel": "High"
    }
    // ...
  ]

• 007 Transactions API

  • Method=GET
  • service root URL/api/v1/:chainId/transactions?start_date=:startTimestamp&end_date=:endTimestamp
  • 備註：Query Parameters : start_date、end_date（startTimestamp變數直接抓當下時間戳記，endTimestamp可以設定成往前幾個天數）
  • Response :

  [
    {
      "category": "Transaction",
      "transactionId": 930071,
      "transactionTime": 1692342345,
      "belongBlock": 230021,
      "transactionStatus": "success",
      "assetType": "Crypto Currency"
    },
    {
      "category": "Transaction",
      "transactionId": 930291,
      "transactionTime": 1689352675,
      "belongBlock": 230676,
      "transactionStatus": "false",
      "assetType": "Evidence"
    },
    {
      "category": "Transaction",
      "transactionId": 930032,
      "transactionTime": 1688342795,
      "belongBlock": 230021,
      "transactionStatus": "pending",
      "assetType": "NFT"
    }
    // ...
  ]

• 008 Transactions API query by Date （日曆功能）

  • Method=GET
  • service root URL/api/v1/:chainId/transactions?start_date=:startTimestamp&end_date=:endTimestamp
  • 備註：Query Parameters : start_date、end_date
  • Response :

  [
    {
      "category": "Transaction",
      "transactionId": 930071,
      "transactionTime": 1692342345,
      "belongBlock": 230021,
      "transactionStatus": "success",
      "assetType": "Crypto Currency"
    }
    // ...
  ]

---

Block 230676 - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/isun/block/230676

• 備註：前一個 URL 點選後，將 230676 這個 block id 用 params 傳至這個 URL

• 009 Block API :

  • Method=GET
  • service root URL/api/v1/:chainId/block/:block_id
  • Response :

    {
    "blockId": 230676,
    "createdDate": 1679998900,
    "stabilityLevel": "High",
    "managementTeam": ["Linda", "Liam"],
    "transactionsContent": [
    {
      "category": "Transaction",
      "hash": "0x773A74Cd884139069fEc25f56f9537631A62773",
      "transactionId": 916841,
      "assetType": "Evidence",
      "transactionStatus": "Failed",
      "transactionTime": 1698742345,
      "belongBlock": 217328,
      "addressFrom": 115588,
      "addressTo": 311382,
      "evidence": 515482,
      "value": 0,
      "transactionFee": 0.01,
      "transactionFeeUnit": "BLT",
      "flagging": null,
      "privateNote": ""
    }
    // ...
    ],
    "miner": 0,
    "reward": 0.01,
    "size": 3523
    }

---

Transaction List of Block 230676 - BAIFA

URL : https://baifa-boy6tsv96-cafeca.vercel.app/en/app/transaction-list?blockId=230676

• 備註：前一個 URL 點選後，將 230676 這個 block id 用 params 傳至此 URL

• 010 Transactions of a block API :

  • Method=GET
  • service root URL/api/v1/:chainId/transactions?start_date=:startTimestamp&end_date=:endTimestamp&block_id=:blockId
  • 備註：Query Parameters : start_date、end_date、block_id（startTimestamp變數直接抓當下時間戳記，endTimestamp可以設定成往前幾個天數）
  • Response :

  [
    {
      "category": "Transaction",
      "transactionId": 916841,
      "assetType": "Evidence",
      "transactionStatus": "Failed",
      "transactionTime": 1698742345
    },
    {
      "category": "Transaction",
      "transactionId": 914025,
      "assetType": "Crypto Currency",
      "transactionStatus": "Success",
      "transactionTime": 1698342345
    },
    {
      "category": "Transaction",
      "transactionId": 930071,
      "assetType": "Crypto Currency",
      "transactionStatus": "Success",
      "transactionTime": 1692342345
    }
    // ...
  ]

---

Transaction 916841 - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/btc/transaction/916841

• 011 Transaction API

  • Method=GET
  • service root URL/api/v1/:chainId/transaction/:transactionId
  • Response :

  {
    "category": "Transaction",
    "transactionId": 916841,
    "transactionTime": 1698742345,
    "assetType": "Evidence",
    "transactionStatus": "Failed",
    "belongBlock": 217328,
    "addressFrom": 115588,
    "addressTo": 311382,
    "evidence": 515482,
    "value": 100,
    "transactionFee": 0.01,
    "flagging": "None",
    "privateNote": ""
  }

---

Currency List - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/currencies

• 012 Currencies API

  • Method=GET
  • service root URL/api/v1/currencies
  • Response :

  [
    {
      "category": "Currency",
      "currencyName": "Bitcoin",
      "redFlag": [
        {
          "category": "Address",
          "addressID": 112840,
          "flagType": "Multiple Transfer",
          "signUpTime": 1686230832
        }
        // ...
      ]
    },
    {
      "category": "Currency",
      "currencyName": "Ethereum",
      "redFlag": [
        {
          "category": "Address",
          "addressID": 112840,
          "flagType": "Multiple Transfer",
          "signUpTime": 1686230832
        }
        // ...
      ]
    }
  ]

---

Bitcoin - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/currencies/btc

• 013 Currency API

  • Method=GET
  • service root URL/api/v1/currency/:currencyId
  • Response :

  {
    "category": "Currency",
    "currencyId": "btc",
    "currencyName": "Bitcoin",
    "price": 27755.4,
    "volumeIn24Hours": 14867304472,
    "totalAmount": 19388600,
    "totalAmountUnit":"BTC",
    "holders": [
      {
        "category": "Address",
        "addressId": 110029,
        "walletType": "Binance-coldwallet",
        "amount": 248567,
      },
      {
        "category": "Address",
        "addressId": 110123,
        "walletType": "Binance-coldwallet",
        "amount": 178010,
      },
      {
        "category": "Address",
        "addressId": 112840,
        "walletType": "Unknown User",
        "amount": 117351,
      },
      {
        "category": "Address",
        "addressId": 114007,
        "walletType": "Unknown User",
        "amount": 93109,
      },
      {
        "category": "Address",
        "addressId": 115588,
        "walletType": "Unknown User",
        "amount": 62352,
      },
    ],
    "totalTransfers": 48010097,
    "redFlag": [
      {
        "category": "Address",
        "addressID": 112840,
        "flagType": "Multiple Transfer",
        "signUpTime": 1686230832,
      },
      // ...
    ],
  },

---

Address 110029 - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/btc/address/110029

• 014 Address API

  • Method=GET
  • service root URL/api/v1/address/:addressId
  • Response :

  {
    "category": "Address",
    "addressId": 110029,
    "address": "0x156f9f74C2775D3190693fEc256dd8843A79",
    "signUpTime": 1667129031,
    "latestActiveTime": 200,
    "relatedAddresses": [110132, 114007],
    "interactedWith": [
      [110132, 114007], // addresses
      [] // contracts
    ],
    "redFlag": [
      {
        "category": "Address",
        "addressID": 110029,
        "flagType": "Multiple Withdraw",
        "createTime": 1686230832,
      },
      // ...
    ],
    "balance": 0,
    "totalSent": 0,
    "totalReceived": 0,
    "privateNote": "",
    "reviews": [],
    "transactionHistory": [],
    "blockProducedHistory": [],
  },

---

Interaction List of Address 110029 - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/btc/address/110029/interaction?type=address

• 015 Interaction List of Address API

  • Method=GET
  • service root URL/api/v1/address/:chainId/:addressId/interaction?type=address
  • Response :

    [
    {
    "category": "Address",
    "addressId": 110132,
    "transactionHistory": [916841, 914025, 930071, 915024, 918402, 912299, 913211, 930291, 920219, 931314]
    },
    {
    "category": "Address",
    "addressId": 114007,
    "transactionHistory": [916841, 914025, 930071, 915024, 918402, 912299, 913211, 930291, 920219, 931314]
    }
    ]

---

Transaction History of Address 114007 and Address 110029 - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/transaction-list?addressId=114007&addressId=110029

• 016 Transaction History of Addresses

  • Method=GET
  • service root URL/api/v1/transaction-list?address_id=:addressId&address-id=:addressId
  • Response :

    [
    {
    "category": "Transaction",
    "transactionId": 916841,
    "assetType": "Evidence",
    "transactionTime": 1698742345,
    "transactionStatus": "Failed"
    },
    {
    "category": "Transaction",
    "transactionId": 914025,
    "assetType": "Crypto Currency",
    "transactionTime": 1698342345,
    "transactionStatus": "Success"
    }
    // ...
    ]

---

Contract 311382 - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/chains/btc/contract/311382

• 017 Contract API

  • Method=GET
  • service root URL/api/v1/:chainId/contract/:contractId
  • Response :

  {
  "contractId": "311382",
  "contractAddress": "0xb61e1747cb5b2b9ff4a5dd18e625c1b55475d4d5",
  "user": "Unknown User",
  "creator": {
    "category": "Address",
    "addressId": 114007
  },
  "createdTime": 1698321919,
  "sourceCode": "",
  "privateNote": "",
  "transactionHistory": [
    {
      "addressFrom": 114007,
      "transactionTime": 1698742345,
      "transactionStatus": "Success"
    },
    {
      "addressFrom": 114007,
      "transactionTime": 1698742345,
      "transactionStatus": "Success"
    }
  ]
  }

---

Red Flag of Bitcoin - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/currencies/btc/red-flag

• 018 Red Flag of A Currency API

  • Method=GET
  • service root URL/api/v1/currency/:currencyId/red-flag
  • Response :

  [
    {
      "category": "Address",
      "addressID": 112840,
      "flagType": "Multiple Transfer",
      "signUpTime": 1686230832
    },
    {
      "category": "Address",
      "addressID": 112840,
      "flagType": "Large Withdraw",
      "signUpTime": 1686330832
    },
    {
      "category": "Address",
      "addressID": 112840,
      "flagType": "Large Deposit",
      "signUpTime": 1686530832
    },
    {
      "category": "Address",
      "addressID": 112840,
      "flagType": "To High Risk Location",
      "signUpTime": 1686430832
    }
    // ...
  ]

---

Black List - BAIFA

URL: https://baifa-boy6tsv96-cafeca.vercel.app/en/app/blacklist

• 019 Black List APT

  • Method=GET
  • service root URL/api/v1/blacklist
  • Response :

  [
    {
      "addressId": 140050,
      "signUpTime": 1681366321,
      "belongChain": "Tether"
    },
    {
      "addressId": 122810,
      "signUpTime": 1687222335,
      "belongChain": "Ethereum"
    },
    {
      "addressId": 121700,
      "signUpTime": 1688223345,
      "belongChain": "Ethereum"
    }
    // ...
  ]

[godmmt]

done.

19 APIs : total used 20 hours (total: 15 URLs)

[godmmt]

this issue total used : 37 hours