Postman

Why

One of the tools we will use to make the API documentation is Postman. Therefore, it is important that we have a standard for the documentation folder structure that we use to make it easier for developers to implement.

Postman Convention

  • Root Collection, filled by platform.
    • This will make it easier for developers to focus on the platform they are working on
    • Example: CMS, Mobile, Web, etc

image

  • Inside the platform folder, create the folder based on screen/page/menu.
    • Note: because it’s paged, it’s natural for endpoint duplication

image

  • Every API MUST have a positive case example and negative case example (Optional)

image

  • Each API must have an explanation in the postman documentation:
    • explanation of what this service is for
    • ENUM mapping explanation (if any). Example: for gender, M (Male) and F (Female), etc
    • explanation of the DATE format used. Example: yyyy-mm-dd, or dd-mm-yyyy, etc

image

image

image

  • in the root collection, it must have the changes log. This will make it easier for developers to understand what changes occur in each update.

image