{"id":2987,"date":"2025-01-07T19:49:08","date_gmt":"2025-01-08T01:49:08","guid":{"rendered":"https:\/\/readme.com\/resources\/?p=2987"},"modified":"2025-01-07T19:49:10","modified_gmt":"2025-01-08T01:49:10","slug":"the-best-rest-api-template-2","status":"publish","type":"post","link":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2","title":{"rendered":"The Best REST API Template"},"content":{"rendered":"\n<p>We tend to set a low bar when it comes to documenting our APIs.<\/p>\n\n\n\n<p>Developers can stomach poring over dense docs for a product that they&#8217;re interested in using, such as Google Maps or Twitter. Spending hours, days, weeks and falling into a support-searching rabbit-hole on Stack Overflow is practically an industry standard.<\/p>\n\n\n\n<p>But what about the devs who don&#8217;t know much about your product, and aren&#8217;t sold on using it yet?<\/p>\n\n\n\n<p>For people who aren&#8217;t already familiar with your product, your reference doc is a&nbsp;<a href=\"https:\/\/blog.readme.io\/a-culture-of-communication-how-to-keep-api-docs-up-to-date\/?ref=blog.readme.com\">window into your actual product<\/a>. Including every edge case and tons of sample code isn&#8217;t enough. Without a great UI, your thorough documentation will be utterly un-navigable, reaching only a sliver of your audience.<\/p>\n\n\n\n<p>The goal is to get your API doc readers engaged and using your product faster. The only way to do that is by putting everything in a template that&#8217;s easy to navigate through.<\/p>\n\n\n\n<p>Here are the best UI features of a REST API template.<\/p>\n\n\n\n<p><strong>Keep Everything On A Single, Dynamic Page<\/strong><\/p>\n\n\n\n<p>Event Tracing (on Windows) has been cited as&nbsp;<a href=\"https:\/\/mollyrocket.com\/casey\/stream_0029.html?ref=blog.readme.com\">one of the worst APIs<\/a>&nbsp;because its documentation is immensely frustrating to navigate. Event Tracing could be a useful tool since it&#8217;s used to&nbsp;<a href=\"https:\/\/spin.atomicobject.com\/2015\/05\/29\/etw-performance-analysis\/?ref=blog.readme.com\">analyze machine performance<\/a>, but its confusing docs scare most people away and endlessly frustrate the users who need it most.<\/p>\n\n\n\n<p>When you go to the Event Tracing API reference library, you see&nbsp;<a href=\"https:\/\/msdn.microsoft.com\/en-us\/library\/windows\/desktop\/bb968803(v=vs.85).aspx?ref=blog.readme.com\">this page<\/a>:<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png\" alt=\"\"\/><\/figure>\n\n\n\n<p>To see a simple GET command, you have to follow a series of steps: click \u201cEvent Tracing,\u201d \u201cEvent Tracing Reference,\u201d \u201cEvent Tracing Functions,\u201d and scroll down a menu of about 30 functions until you&#8217;re finally navigated to &#8220;<a href=\"https:\/\/msdn.microsoft.com\/en-us\/library\/windows\/desktop\/aa964840(v=vs.85).aspx?ref=blog.readme.com\">TdhGetEventInformation function<\/a>.\u201d<\/p>\n\n\n\n<p>When your users have to click through different links within your API reference docs, it becomes too difficult to find anything.<\/p>\n\n\n\n<p>Compare that experience with what you get looking through&nbsp;<a href=\"https:\/\/plaid.com\/docs\/api\/?ref=blog.readme.com#response-codes\">Plaid<\/a>&#8216;s API doc. Plaid&#8217;s developers put the most important info at the top\u2014the introduction, authentication, and error-handling. But since the entire doc is on one page, readers with a burning question can CTRL-F the whole page to find what they need.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/Plaid.png\" alt=\"\"\/><\/figure>\n\n\n\n<p>As Plaid shows, the simplest solution is to keep your entire document on one dynamic page. You can do that by including:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong><a href=\"https:\/\/blog.readme.io\/why-these-api-docs-are-better-than-yours-and-what-you-can-do-about-it\/?ref=blog.readme.com\">Anchor links<\/a><\/strong>\u00a0where your URL changes to match whatever section you&#8217;re viewing.<\/li>\n\n\n\n<li><strong>Navigation bars<\/strong>\u00a0that hover on one side of your screen as you scroll through the document.<\/li>\n<\/ul>\n\n\n\n<p>The anchor links on&nbsp;<a href=\"https:\/\/plaid.com\/docs\/quickstart\/?ref=blog.readme.com#step-2-custom-integration\">Plaid<\/a>&#8216;s API reference provide simple benchmarks for that section. The navigation bar on the left shows readers where they are within the doc&#8217;s overall scope.<\/p>\n\n\n\n<p>Instead of forcing your API users to navigate through an endless maze of links, put everything on a single, easy-to-navigate page. In a single page format, anything they need is at the tip of their fingertips\u2014no clicking through page-after-page necessary.<\/p>\n\n\n\n<p><strong>Organize Your Doc in a Three-Pane View<\/strong><\/p>\n\n\n\n<p>Code without context\u00a0is just code. That&#8217;s why most docs include clarifications and summaries\u2014so the reader can understand the practical applications of the code, and what their program will be able to do once the software is integrated.<\/p>\n\n\n\n<p>But including these explanations and summaries isn&#8217;t enough. They have to be accessible only when and where your readers need them.<\/p>\n\n\n\n<p><a href=\"https:\/\/web.archive.org\/web\/20160517024645\/https:\/\/developer.paypal.com\/docs\/classic\/paypal-payments-standard\/integration-guide\/authcapture\/\">Paypal&#8217;s<\/a>&nbsp;original documentation site had two panes. But since its navigation bar was not dynamic, readers lost their navigation menu\u2014and context\u2014as they scrolled down the page. That&#8217;s why critics of this documentation&nbsp;<a href=\"http:\/\/blogg.openend.se\/2012\/9\/7\/the-worst-documentation-experience-ever?ref=blog.readme.com\">say that<\/a>&nbsp;\u201cthe structure of the documentation is a catastrophe [&#8230;] The descriptions of how to set things up have no links to the APIs and the APIs are not linked to examples.\u201d<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/paypal1.png\" alt=\"\"\/><\/figure>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/paypal2.png\" alt=\"\"\/><\/figure>\n\n\n\n<p>A better solution\u2014and one that Paypal later adopted\u2014is using a single page with three panes.<\/p>\n\n\n\n<p><a href=\"https:\/\/clearbit.com\/docs?python=&amp;ref=blog.readme.com#webhooks\">Clearbit<\/a>&nbsp;does this by putting dynamic nav bars in the left pane, explanations in the middle, and sample code on the right. Putting all the info together means that devs can see how everything works in context faster, and start trying their hand at the code sooner.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/Clearbit--2-.png\" alt=\"\"\/><\/figure>\n\n\n\n<p>A three-pane view lets the user curate their own experience. It doesn&#8217;t prioritize explanations over sample code (or vice versa). Whether you want to be briefed in plain English or to skim the sample code, a three-pane view puts all relevant info in one place and lets the user adjust as needed.<\/p>\n\n\n\n<p>There&#8217;s only so much real-estate on your screen. Letting readers curate their own experiences means they can choose what to look at, without you risking decisions that may limit your audience.<\/p>\n\n\n\n<p><strong>Let Readers Make Calls with an API Explorer<\/strong><\/p>\n\n\n\n<p>The #1 thing your API doc readers want is to see what your API is capable of\u2014and the best way to do that is by giving them a chance to try it themselves.<\/p>\n\n\n\n<p>Adding in an API Explorer lets you engage people of all technical backgrounds to make some of the most common calls in a few seconds, and without leaving your site.<\/p>\n\n\n\n<p>Quickstarts that let you create a developer sandbox are incredibly popular, but, they too come with some friction.&nbsp;<a href=\"https:\/\/docs.docusign.com\/?ref=blog.readme.com\">Docusign<\/a>&nbsp;requires the reader to first go to a separate page to create a (free) Sandbox account, verify their email, set up a password, and then they can set up their API key.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/docusign-sandbox.png\" alt=\"\"\/><\/figure>\n\n\n\n<p>This works fine, and it&#8217;s certainly better than setting up or adjusting your developer environment. But you can make this process even easier, by setting up an API explorer.&nbsp;<a href=\"https:\/\/www.flickr.com\/services\/api\/explore\/flickr.people.getPublicPhotos?ref=blog.readme.com\">Flickr&#8217;s<\/a>&nbsp;&#8220;App Garden,&#8221; eliminates all that friction. It lets you make calls straight from the documentation page, no login or authentication necessary.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/Flickr-API-Explorer.png\" alt=\"\"\/><\/figure>\n\n\n\n<p>If your readers feel like it&#8217;s a hassle to learn about your API in general, they&#8217;ll be quick to abandon your site. The more steps there are to actually working with your API, the greater the barrier to entry. Having to create an account, log in, and navigate back is an absurd amount of steps to get a gist of how a product works.<\/p>\n\n\n\n<p>The simpler you can make it for readers to reach your API, the sooner they&#8217;ll learn what it&#8217;s capable of.<\/p>\n\n\n\n<p><strong>Create Your Own Template<\/strong><\/p>\n\n\n\n<p>Most developerss would rather outline all their error codes than think about their documentation&#8217;s UI. The truth is, you need to pair that with navigable UI to maintain your readers&#8217; interest\u2014especially if they&#8217;re not already familiar with the work you do.<\/p>\n\n\n\n<p>If you want to save time building your own API template, ReadMe offers standardized templates that use these features.&nbsp;<a href=\"https:\/\/dash.readme.io\/signup?ref=blog.readme.com\">Click here<\/a>&nbsp;to learn more.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>We tend to set a low bar when it comes to documenting our APIs. Developers can stomach poring over dense docs for a product that they&#8217;re interested in using, such as Google Maps or Twitter. Spending hours, days, weeks and falling into a support-searching rabbit-hole on Stack Overflow is practically an industry standard. But what [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"content-type":"","inline_featured_image":false,"footnotes":""},"categories":[22],"tags":[],"ppma_author":[2],"class_list":["post-2987","post","type-post","status-publish","format-standard","hentry","category-api-tips"],"acf":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v23.0 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>Optimizing Heroku&#039;s Logging Firehose for Enhanced Monitoring<\/title>\n<meta name=\"description\" content=\"Unlock the full potential of Heroku&#039;s logging system with our insights on refining HTTP logs and integrating powerful analytics tools.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Optimizing Heroku&#039;s Logging Firehose for Enhanced Monitoring\" \/>\n<meta property=\"og:description\" content=\"Unlock the full potential of Heroku&#039;s logging system with our insights on refining HTTP logs and integrating powerful analytics tools.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2\" \/>\n<meta property=\"og:site_name\" content=\"ReadMe: Resource Library\" \/>\n<meta property=\"article:published_time\" content=\"2025-01-08T01:49:08+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2025-01-08T01:49:10+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png\" \/>\n<meta name=\"author\" content=\"readmedev\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"readmedev\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"7 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2\",\"url\":\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2\",\"name\":\"Optimizing Heroku's Logging Firehose for Enhanced Monitoring\",\"isPartOf\":{\"@id\":\"https:\/\/readme.com\/resources\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#primaryimage\"},\"image\":{\"@id\":\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#primaryimage\"},\"thumbnailUrl\":\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png\",\"datePublished\":\"2025-01-08T01:49:08+00:00\",\"dateModified\":\"2025-01-08T01:49:10+00:00\",\"author\":{\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/cf2f75bdb1d0398bebccfae9675a6418\"},\"description\":\"Unlock the full potential of Heroku's logging system with our insights on refining HTTP logs and integrating powerful analytics tools.\",\"breadcrumb\":{\"@id\":\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#primaryimage\",\"url\":\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png\",\"contentUrl\":\"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/readme.com\/resources\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"The Best REST API Template\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/readme.com\/resources\/#website\",\"url\":\"https:\/\/readme.com\/resources\/\",\"name\":\"ReadMe: Resource Library\",\"description\":\"Making API documentation better for everyone\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/readme.com\/resources\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/cf2f75bdb1d0398bebccfae9675a6418\",\"name\":\"readmedev\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/image\/8b12c5a3a20906722873c146dee0bd9b\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/d5d17a7fdf698ca54de2619cb66e3b1608c9056ad901d2f23e55a4ec6d57a239?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/d5d17a7fdf698ca54de2619cb66e3b1608c9056ad901d2f23e55a4ec6d57a239?s=96&d=mm&r=g\",\"caption\":\"readmedev\"},\"sameAs\":[\"https:\/\/readme.com\/resources\"],\"url\":\"https:\/\/readme.com\/resources\/author\/readmedev\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Optimizing Heroku's Logging Firehose for Enhanced Monitoring","description":"Unlock the full potential of Heroku's logging system with our insights on refining HTTP logs and integrating powerful analytics tools.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2","og_locale":"en_US","og_type":"article","og_title":"Optimizing Heroku's Logging Firehose for Enhanced Monitoring","og_description":"Unlock the full potential of Heroku's logging system with our insights on refining HTTP logs and integrating powerful analytics tools.","og_url":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2","og_site_name":"ReadMe: Resource Library","article_published_time":"2025-01-08T01:49:08+00:00","article_modified_time":"2025-01-08T01:49:10+00:00","og_image":[{"url":"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png"}],"author":"readmedev","twitter_card":"summary_large_image","twitter_misc":{"Written by":"readmedev","Est. reading time":"7 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2","url":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2","name":"Optimizing Heroku's Logging Firehose for Enhanced Monitoring","isPartOf":{"@id":"https:\/\/readme.com\/resources\/#website"},"primaryImageOfPage":{"@id":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#primaryimage"},"image":{"@id":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#primaryimage"},"thumbnailUrl":"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png","datePublished":"2025-01-08T01:49:08+00:00","dateModified":"2025-01-08T01:49:10+00:00","author":{"@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/cf2f75bdb1d0398bebccfae9675a6418"},"description":"Unlock the full potential of Heroku's logging system with our insights on refining HTTP logs and integrating powerful analytics tools.","breadcrumb":{"@id":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/readme.com\/resources\/the-best-rest-api-template-2"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#primaryimage","url":"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png","contentUrl":"https:\/\/blog.readme.com\/content\/images\/2016\/11\/microsoft.png"},{"@type":"BreadcrumbList","@id":"https:\/\/readme.com\/resources\/the-best-rest-api-template-2#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/readme.com\/resources\/"},{"@type":"ListItem","position":2,"name":"The Best REST API Template"}]},{"@type":"WebSite","@id":"https:\/\/readme.com\/resources\/#website","url":"https:\/\/readme.com\/resources\/","name":"ReadMe: Resource Library","description":"Making API documentation better for everyone","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/readme.com\/resources\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/cf2f75bdb1d0398bebccfae9675a6418","name":"readmedev","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/image\/8b12c5a3a20906722873c146dee0bd9b","url":"https:\/\/secure.gravatar.com\/avatar\/d5d17a7fdf698ca54de2619cb66e3b1608c9056ad901d2f23e55a4ec6d57a239?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/d5d17a7fdf698ca54de2619cb66e3b1608c9056ad901d2f23e55a4ec6d57a239?s=96&d=mm&r=g","caption":"readmedev"},"sameAs":["https:\/\/readme.com\/resources"],"url":"https:\/\/readme.com\/resources\/author\/readmedev"}]}},"authors":[{"term_id":2,"user_id":1,"is_guest":0,"slug":"readmedev","display_name":"readmedev","avatar_url":"https:\/\/secure.gravatar.com\/avatar\/f827600cb59eb7b39ae598802b917c6e5fba7a7e93daa9bd5ef3a7ef04af8d9f?s=96&d=mm&r=g","first_name":"Ryan","last_name":"parker","position":"","slogan":"","description":""}],"_links":{"self":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts\/2987","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/comments?post=2987"}],"version-history":[{"count":0,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts\/2987\/revisions"}],"wp:attachment":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/media?parent=2987"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/categories?post=2987"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/tags?post=2987"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/ppma_author?post=2987"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}