April 2023 Summaries

Polymorphism is an important concept in API development to help achieve objectives such as easy code changes and scalable API design. It refers to the possibility of using the same endpoint for similar but different objects, reducing the amount of endpoint duplications. In this article, the author explains how polymorphism can be used in API development with examples from a real estate agency application. They also discuss how to properly document polymorphic resources with OpenAPI or AsyncAPI specifications based on JSON Schema. The article covers inheritance and DRY patterns, discriminator support, and provides an example of how to use the oneOf combinator for defining alternatives in API documentation.

Polymorphism is a crucial concept in API development, enabling the use of a single endpoint to handle similar but distinct objects, thereby streamlining API design and reducing endpoint duplication. The article illustrates this using a real estate agency application, where a single endpoint can process both house and apartment data by identifying shared and unique attributes within each accommodation type. JSON Schema's combinators like `anyOf` and `oneOf` support this approach by allowing the inclusion of varied schemas, while the discriminator keyword in OpenAPI and AsyncAPI helps distinguish between object types based on specific properties. This method not only simplifies API consumption but also aligns with the Single Source of Truth and Don’t Repeat Yourself principles, thereby enhancing maintainability and scalability. The documentation emphasizes the importance of clear API documentation, as demonstrated through Bump.sh, to ensure that consumers are well-informed about the polymorphic nature of APIs.

An API contract is a document that outlines an API's behavior and usage guidelines. It helps ensure consistency and predictability in interactions with the API, promotes shared understanding, and assists in streamlining processes for both internal and external users. API contracts can take various forms such as documents, formal specifications, or code examples, often following established standards like OpenAPI, gRPC, GraphQL, AsyncAPI, or Blueprint. They should be simple, well-documented, and thoroughly tested against the contract before release. Practices like specifying expected behavior, API versioning, documenting data formats, limitations, and restrictions are crucial in designing effective API contracts.