...
- Using 'POST' instead of 'GET' for message retrieval
A 'POST' API call for retrieval of messages aligns with HTTP semantics, especially considering the nature of Match Connect. In line with HTTP semantics and RESTful best practices, 'GET' requests should per definition be cacheable. In Match Connect message retrieval triggers a mutation, because messages are no longer available after retrieval. Therefore, the information in Match Connect is non-cacheable.
The 'POST' method better reflects the intention of performing a server-side operation and helps avoid unintended caching of mutable operations, enhancing the overall robustness and correctness of Match Connect.
Additional information about RESTful best practices can be found here.
Additional information about HTTP semantics can be found here.
2.4.4 Automatically generated and manually curated Swagger
The use of both an automatically generated and manually curated Swagger serves a dual purpose.
The automatically generated Swagger reflects the implementation of the API endpoints in its current state with accurate details on the sub-schemas. This representation ensures that implementers have access to the most up-to-date information.
The manually curated Swagger plays a crucial role in communication to stakeholders. This representation reflects a broader overview of the relevant endpoints and provides insights into planned future endpoints. This curated version therefore also acts as a guide to provide a clearer understanding of the future development of Match Connect.
Together, these two approaches provide important information about technical accuracy and communication about the development of Match Connect.