{"id":871,"date":"2018-05-24T08:27:47","date_gmt":"2018-05-24T08:27:47","guid":{"rendered":"http:\/\/adriangrigoras.com\/blog\/?p=871"},"modified":"2018-05-24T08:27:47","modified_gmt":"2018-05-24T08:27:47","slug":"postman-collections-default-part-api-documentation","status":"publish","type":"post","link":"https:\/\/adriangrigoras.com\/blog\/postman-collections-default-part-api-documentation\/","title":{"rendered":"Postman Collections Should be A Default Part of Your API Documentation"},"content":{"rendered":"

I\u2019m taking time to showcase any API I come across who have published their OpenAPI definitions to GitHub like\u00a0New York Times<\/a>,\u00a0Box<\/a>,\u00a0Stripe<\/a>,\u00a0SendGrid<\/a>,\u00a0Nexmo<\/a>, and others have. I\u2019m also taking the time to publish stories showcasing any API provider who similarly publishes Postman Collections as part of their API documentation. Next up on my list is\u00a0the Triathlon API<\/a>, who provides a pretty sophisticated API stack for managing triathlons around the world, complete with a list of Postman Collections for exploring and getting up and running with their API.<\/p>\n

Much like Okta, which I wrote about last week<\/a>, the\u00a0Triathlon API has broken their Postman Collections into individual service collections<\/a>\u00a0and provides a nice list of them for easy access. Making it quick and easy to get up and running making calls to the API. Something that ALL API providers should be doing. Sorry, but Postman Collections should be a default part of your API documentation, just like an OpenAPI definition should the driver of your interactive API docs, and the rest of your API lifecycle.<\/p>\n

Every provider should be maintaining their OpenAPI definitions, as well as Postman Collections on GitHub, and baking them into their API documentation. Your OpenAPI should be the central truth for your API operations, and then you can easily import it, and generate Postman Collections as you design, test, and evolve your API using the Postman development suite. I know there are many API providers who haven\u2019t caught up to this approach to delivering API resources, but it is something they need to tune into and make the necessary shift in how you are delivering your resources.<\/p>\n

In addition to regular stories like this on the blog, you will find me reaching out to individual API providers asking if they have an OpenAPI and\/or Postman Collections. I\u2019m personally invested in getting API providers to adopt their API definition formats. I want to see their APIs present in\u00a0my API Stack work<\/a>, as well as other API discovery projects I\u2019m contributing to like Streamdata.io, Postman Network, APIs.Guru, and others. Making sure your APIs are discovered and making sure you are getting out of the way of your developers by baking API definitions into your API operations\u2013it is just what you do in 2018.<\/p>\n

 <\/p>\n

source:\u00a0https:\/\/dzone.com\/articles\/using-postman-to-explore-the-triathlon-api<\/p>\n","protected":false},"excerpt":{"rendered":"

I\u2019m taking time to showcase any API I come across who have published their OpenAPI definitions to GitHub like\u00a0New York Times,\u00a0Box,\u00a0Stripe,\u00a0SendGrid,\u00a0Nexmo, and others have. I\u2019m also taking the time to publish stories showcasing any API provider who similarly publishes Postman Collections as part of their API documentation. Next up on my list is\u00a0the Triathlon API,\u2026 Read More »<\/a><\/span><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[30],"tags":[],"class_list":["post-871","post","type-post","status-publish","format-standard","hentry","category-architecture"],"_links":{"self":[{"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/posts\/871","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/comments?post=871"}],"version-history":[{"count":1,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/posts\/871\/revisions"}],"predecessor-version":[{"id":872,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/posts\/871\/revisions\/872"}],"wp:attachment":[{"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/media?parent=871"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/categories?post=871"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/adriangrigoras.com\/blog\/wp-json\/wp\/v2\/tags?post=871"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}