This document defines key terms and concepts related to the API architecture and data contracts used in this project.
A machine-readable definition of an API interface. It provides a clear description of the available resources, how to interact with them, and the legal and operational terms governing their use. The contract is a comprehensive agreement between the API provider and the consumer.
Key Components of the API Contract:
The technical specification of the API. In this project, the def_Api table unifies all components of an API, particularly the REST webhook endpoints. The ServiceCode field in the def_Webhook and def_Api tables is used to uniquely identify and link the components of a specific API.
A live, auto-generated document that provides an online, interactive blueprint of the API endpoints. As endpoints are added or modified, the blueprint is automatically updated, ensuring the documentation is always current.
A YAML-based language used for defining RESTful APIs. It provides a structured way to describe an API, which can then be used to generate client/server code and comprehensive user documentation.
The legal agreement that governs the use of the API. It outlines what is permitted and what is forbidden, forming a critical part of the overall API contract.
The policy that details how the platform handles data, particularly end-user data. It is a cornerstone of trust between the provider, developers, and end-users.
A commitment that defines the level of service, performance, and reliability that API consumers can expect. This includes metrics for uptime, response times, and support.
The API contract includes several layers of licensing:
A policy that clearly communicates the lifecycle of the API. It specifies how long an API will be supported and what kind of notice consumers will receive before it is retired. This is essential for building trust and allowing consumers to plan for changes.
A mechanism for controlling the number of requests a consumer can make to the API within a given timeframe. Rate limits are a key part of the operational contract, ensuring fair usage and protecting the service from abuse.
The percentage of time the API is expected to be operational and available for use. This is a core component of the SLA.
The model that defines the cost of using the API. It stipulates the value exchanged between the provider and the consumer as part of the contract.
The level and channels of support that the API provider offers to consumers. This can include documentation, forums, direct email support, or dedicated support channels, and is a critical part of a healthy provider-consumer relationship.