Through all this years I have been using code first approach as my standard for developing APIs but participating in Postman API Hackathon and getting introduced to OpenAPI 3.0 has changed my perspective a lot. Code first approach consist of developing APIs via code first then writing documents and integration, this is the standard approach but one of the biggest drawback is writing and maintaining documentation and as API changes we need to update the documentations and integrations accordingly . Also creating mocks and maintaining API standards is a hell.
Postman and OpenAPI 3.0 comes to the rescue !
While going through the features that Postman workspace provides I came across OpenAPI specification. When I dinged in further I found this video that brought me to the world of API first development approach.
The API first approach consist of first writing the specification for API using something like Open API 3.0 , RAML or GraphQL specification after the specifications are written Postman provides all the tools necessary for automatically creating document , collections and even a completely working mock server !
For my Hackathon submission I planned on using the code first approach , but learning about API first has changed my perspective ! and OpenAPI 3.0 standard for writing specification is really complete and in-depth
You can read about the OpenAPI specification here: https://swagger.io/specification/
Or you can check out the OpenAPI 3.0 specification I am writing for my Open Source Social Network API submission as part of Postman API Hackathon and get inspired here : https://github.com/OSSNAPI/OpenAPI-spec