Update API docs with more info

src/Packagist/WebBundle/Resources/public/js/layout.js

@@ -42,4 +42,10 @@
             e.preventDefault();
         });
     });
-})(jQuery, humane);
+
+    $('.toc a').click(function (e) {
+        setTimeout(function () {
+            scrollTo(0, $($(e.target).attr('href')).offset().top - 65);
+        }, 0);
+    });
+})(jQuery, humane);

src/Packagist/WebBundle/Resources/public/js/view.js

@@ -172,7 +172,7 @@
     });
 
     var versionsList = $('.package .versions')[0];
-    if (versionsList.offsetHeight < versionsList.scrollHeight) {
+    if (versionsList && versionsList.offsetHeight < versionsList.scrollHeight) {
         $('.package .versions-expander').removeClass('hidden').on('click', function () {
             $(this).addClass('hidden');
             $(versionsList).css('max-height', 'inherit');

src/Packagist/WebBundle/Resources/views/ApiDoc/index.html.twig

@@ -2,18 +2,42 @@
 {% block content %}
 
 <h2 class="title">API documentation</h2>
-<p>Packagist has a public API to consume data. See bellow the most important URIs:</p>
 
-<ul>
-  <li><a href="#list-packages-by-organization">List packages by organization</a></li>
-  <li><a href="#search-packages-by-tag">Search packages by tag</a></li>
-  <li><a href="#search-packages-by-name">Search packages by name</a></li>
-  <li><a href="#search-packages-by-type">Search packages by type</a></li>
-  <li><a href="#get-package-by-name">Get a package by name</a></li>
+<ul class="toc">
+  <li><a href="#list-packages">Listing package names</a>
+    <ul>
+      <li><a href="#list-packages-all">All packages</a></li>
+      <li><a href="#list-packages-by-organization">By organization</a></li>
+      <li><a href="#list-packages-by-type">By type</a></li>
+    </ul>
+  </li>
+  <li><a href="#search-packages">Searching for packages</a>
+    <ul>
+      <li><a href="#search-packages-by-tag">By tag</a></li>
+      <li><a href="#search-packages-by-name">By name</a></li>
+      <li><a href="#search-packages-by-type">By type</a></li>
+    </ul>
+  </li>
+  <li><a href="#get-package-data">Getting package data</a></li>
 </ul>
 
+
 <section class="col-d-12">
-<h3 id="list-packages-by-organization"> List packages by organization </h3>
+<h3 id="list-packages">Listing package names</h3>
+<h4 id="list-packages-all">List all packages</h4>
+<pre>
+GET https://packagist.org/packages/list.json
+<code>
+{
+  "packageNames": [
+    "[vendor]/[package]",
+    ...
+  ]
+}
+</code></pre>
+<p>Working example: <code><a href="https://packagist.org/packages/list.json">https://packagist.org/packages/list.json</a></code></p>
+
+<h4 id="list-packages-by-organization">List packages by organization</h4>
 <pre>
 GET https://packagist.org/packages/list.json?vendor=[vendor]
 <code>
@@ -24,61 +48,73 @@ GET https://packagist.org/packages/list.json?vendor=[vendor]
   ]
 }
 </code></pre>
-</section>
+<p>Working example: <code><a href="https://packagist.org/packages/list.json?vendor=composer">https://packagist.org/packages/list.json?vendor=composer</a></code></p>
 
-<h3>Search</h3>
+<h4 id="list-packages-by-type">List packages by type</h4>
+<pre>
+GET https://packagist.org/packages/list.json?type=[type]
+<code>
+{
+  "packageNames": [
+    "[vendor]/[package]",
+    ...
+  ]
+}
+</code></pre>
+<p>Working example: <code><a href="https://packagist.org/packages/list.json?type=composer-plugin">https://packagist.org/packages/list.json?type=composer-plugin</a></code></p>
 
-<p>Search results are paginated and you can change the pagination step by using the per_page parameter. For example <code>https://packagist.org/search.json?q=[query]&amp;per_page=5</code></p>
+</section>
 
 
 <section class="col-d-12">
-<h3 id="search-packages-by-tag">Search packages by tag</h3>
+<h3 id="search-packages">Search packages</h3>
+
+<p>Search results are paginated and you can change the pagination step by using the per_page parameter. For example <code>https://packagist.org/search.json?q=[query]&amp;per_page=5</code></p>
+
+<h4 id="search-packages-by-name">Search packages by name</h4>
 <pre>
-GET https://packagist.org/search.json?tags=[tag]
+GET https://packagist.org/search.json?q=[query]
 <code>
 {
-  "results": [
+  "results" : [
     {
       "name": "[vendor]/[package]",
       "description": "[description]",
       "url": "https://packagist.org/packages/[vendor]/[package]",
-      "repository": "[repository url]",
+      "repository": [repository url],
       "downloads": [number of downloads],
       "favers": [number of favers]
-    }
+    },
     ...
   ],
-  "total": [numbers of results]
+  "total": [number of results],
+  "next": "https://packagist.org/search.json?q=[query]&amp;page=[next page number]"
 }
-</code>
-</section>
-
+</code></pre>
+<p>Working example: <code><a href="https://packagist.org/search.json?q=monolog">https://packagist.org/search.json?q=monolog</a></code></p>
 
-<section class="col-d-12">
-<h3 id="search-packages-by-name">Search packages by name </h3>
+<h4 id="search-packages-by-tag">Search packages by tag</h4>
 <pre>
-GET https://packagist.org/search.json?q=[query]
+GET https://packagist.org/search.json?tags=[tag]
 <code>
 {
-  "results" : [
+  "results": [
     {
       "name": "[vendor]/[package]",
       "description": "[description]",
       "url": "https://packagist.org/packages/[vendor]/[package]",
-      "repository": [repository url],
+      "repository": "[repository url]",
       "downloads": [number of downloads],
       "favers": [number of favers]
-    },
+    }
     ...
   ],
-  "total": [number of results],
-  "next": "https://packagist.org/search.json?q=[query]&amp;page=[next page number]"
+  "total": [numbers of results]
 }
-</code>
-</section>
+</code></pre>
+<p>Working example: <code><a href="https://packagist.org/search.json?q=monolog&amp;tags=psr-3">https://packagist.org/search.json?q=monolog&amp;tags=psr-3</a></code></p>
 
-<section class="col-d-12">
-<h3 id="search-packages-by-type">Search packages by type </h3>
+<h4 id="search-packages-by-type">Search packages by type</h4>
 <pre>
 GET https://packagist.org/search.json?q=[query]&amp;type=symfony-bundle
 <code>
@@ -97,11 +133,53 @@ GET https://packagist.org/search.json?q=[query]&amp;type=symfony-bundle
   "total": [number of results],
   "next": "https://packagist.org/search.json?q=[query]&amp;page=[next page number]"
 }
-</code>
+</code></pre>
+<p>Working example: <code><a href="https://packagist.org/search.json?q=monolog&amp;type=symfony-bundle">https://packagist.org/search.json?q=monolog&amp;type=symfony-bundle</a></code></p>
 </section>
 
+
 <section class="col-d-12">
-<h3 id="get-package-by-name">Get package by name </h3>
+<h3 id="get-package-data">Getting package data</h3>
+
+<h4 id="get-package-by-name">Using the Composer metadata</h4>
+
+<p>This is the preferred way to access the data as it is always up to date, and dumped to static files so it is very efficient on our end.</p>
+
+<p>You can also send If-Modified-Since headers to limit your bandwidth usage and cache the files on your end with the proper filemtime set according to our Last-Modified header.</p>
+
+<p>There are a few gotchas though with using this method:
+
+<ul>
+  <li>It only provides you with the package metadata but not information about the maintainers, download stats or github info.</li>
+  <li>It contains providers information which must be ignored but can appear confusing at first. This will disappear in the future though.</li>
+</ul>
+</p>
+
+<pre>
+GET https://packagist.org/p/[vendor]/[package].json
+<code>
+{
+  "packages": {
+    "[vendor]/[package]": {
+      "[version1]": {
+        "name": "[vendor]/[package],
+        "description": [description],
+        // ...
+      },
+      "[version2]": {
+        // ...
+      }
+      // ...
+    }
+  }
+}
+</code></pre>
+<p>Working example: <code><a href="https://packagist.org/p/monolog/monolog.json">https://packagist.org/p/monolog/monolog.json</a></code></p>
+
+<h4 id="get-package-by-name">Using the API</h4>
+
+<p>The JSON API for packages gives you all the infos we have including downloads, dependents count, github info, etc. However it is generated dynamically so for performance reason we cache the responses for one hour. As such if the static file endpoint described above is enough please use it instead.</p>
+
 <pre>
 GET https://packagist.org/packages/[vendor]/[package].json
 <code>
@@ -122,7 +200,9 @@ GET https://packagist.org/packages/[vendor]/[package].json
     "favers": [number of favers]
   }
 }
-</code>
+</code></pre>
+<p>Working example: <code><a href="https://packagist.org/packages/monolog/monolog.json">https://packagist.org/packages/monolog/monolog.json</a></code></p>
+
 </section>