API Standards

This document outlines the naming conventions and design standards for BHN APIs

Clear naming standards enhance clarity, maintainability, and interoperability across different APIs and projects. Adhering to these standards ensures a seamless experience for API consumers and developers.

Principles

• Consistency: Maintain consistency in naming conventions across endpoints, resources, parameters, and HTTP methods.
• Clarity: Use clear and descriptive names that convey the purpose and functionality of each resource and endpoint.
• Readability: Prioritize readability over brevity. Avoid overly abbreviated or cryptic names.
• Predictability: Ensure that names accurately reflect the expected behavior and outcomes of API endpoints.

Resource Naming

• Use Nouns: Resources should be named using plural nouns whenever possible. For example, /orders instead of /order.
• Descriptive Names: Choose descriptive names that reflect the nature of the resource. For example, /orders for a resource representing orders.
• Avoid Verbs: Resource names should not contain verbs. Verbs should be reserved for HTTP methods.

Endpoint Naming

• Use Nouns: Endpoints should also use nouns to represent resources. For example, /orders instead of /getOrders.
• Use HTTP Methods for Actions: HTTP methods (GET, POST, PUT, DELETE) should define the action to be performed on the resource. For example, GET /orders to retrieve a list of orders.
• Avoid Ambiguity: Endpoint names should be unambiguous and clearly indicate the operation being performed.

Versioning

• Incorporate Versioning in URL: If versioning is necessary, incorporate it into the URL structure. For example, /v3/orders for version 3 of the orders API.
• Semantic Versioning: Follow semantic versioning principles for API versioning to indicate backward compatibility and changes.