📄️ IPA-1 Improvement Proposal for APIs
IPA stands for Improvement Proposal for APIs, which is a design document
📄️ IPA-2 IPA Numbering
The IPA system provides a mechanism to index and has a single source of truth
📄️ IPA-3 IPA Style and Guidance
IPAs are most useful when they are clear and concise and cover a single topic or
📄️ IPA-4 Glossary
Common terminology across IPAs.
📄️ IPA-5: Documenting Exceptions to IPAs
Following IPAs may not be possible for historical or technical reasons. For such
📄️ IPA-100: Language
Developers worldwide use MongoDB, and many customers who don't speak English as
📄️ IPA-101: Resource-Oriented Design
Resource-oriented design is a pattern for specifying APIs based on several
📄️ IPA-102: Resource Identifiers
Most APIs expose resources (their primary nouns) that users can create,
📄️ IPA-103: Methods
An API is composed of one or more methods, which represent a specific operation
📄️ IPA-104: Get
In REST APIs, it is customary to make a GET request to a resource's URI (for
📄️ IPA-105: List
In many APIs, it is customary to make a GET request to a collection's URI (for
📄️ IPA-106: Create
In REST APIs, it is customary to make a POST request to a collection's URI
📄️ IPA-107: Update
In REST APIs, it is customary to make a PATCH or PUT request to a resource's
📄️ IPA-108: Delete
In REST APIs, it is customary to make a DELETE request to a resource's URI
📄️ IPA-109: Custom Methods
Resource-oriented design uses custom methods to provide a means to
📄️ IPA-110: Pagination
APIs often need to provide collections of data, most commonly in the List
📄️ IPA-111: Server-Modified Values and Defaults
Server-modified and default values often make it harder to implement
📄️ IPA-112: Field Names
Naming fields in a way that is intuitive to users can often be one of the most
📄️ IPA-113: Singleton Resources
An API may define singleton resources. A singleton resource must always
📄️ IPA-114: Errors
Effective error communication is an important part of designing simple and
📄️ IPA-115: Envelope Object
Some clients might not be able to access the HTTP response headers and/or status
📄️ IPA-116: Backwards Compatibility
APIs are fundamentally contracts with users, and users often write code against
📄️ IPA-117: Documentation
Documentation serves as a primary tool for clients to better understand an API
📄️ IPA-118: Extensible by Default
Signaling to clients any intentions for future extensibility and designing APIs
📄️ IPA-119: Multi-Cloud Support by Default
Considering support for all cloud partners supported by Atlas, even if not
📄️ IPA-120: Versioning
API producers should avoid incrementing the API version where possible,
📄️ IPA-121: Datetime
Datetime can be confusing as timezones and calendars come into play. To help
📄️ IPA-122: Standard Codes
References to countries and languages across the API platform need to adhere to
📄️ IPA-123: Enums
By leveraging enumerations (enums) whenever a field only accepts a discrete set
📄️ IPA-124: Repeated Fields
Providing clients with lists of data can be complex. Aligning on a single
📄️ IPA-125: Single Type in Request and Response
API requests and responses should strive for clarity by representing each field
📄️ IPA-126: Top-Level API Names
Top-level API names direct customers to the core services or functional areas
📄️ IPA-127: Declarative-Friendly Interfaces
Experimental
📄️ IPA-128: Stability Levels
Experimental
📄️ IPA-129: Query Parameters
Query parameters can be appended to the request URI and are useful for providing