Extend docs for retrieving the package metadata

Author: IgorBenko

docs/api/package-metadata.md

@@ -2,10 +2,20 @@
 
 To read the package metadata via API, use the Composer API on your Private Packagist repository.
 
+This is useful when you need to programmatically access package metadata beyond what's available through the Private Packagist API
+(for example to read custom configuration from the `extra` section of a package's composer.json). 
+
 Read more about the API: https://packagist.org/apidoc#get-package-data
 
+
 ### Example implementation
 
+The process works as follows:
+1. Get the JSON from `https://repo.packagist.com/<org>/p2/<package>.json`
+2. Authenticate using username `token` and an Authentication Token as password
+3. Decode the JSON as nested arrays
+4. Use [MetadataMinifier](https://github.com/composer/metadata-minifier) to expand the metadata for each package version: `$metadata = MetadataMinifier::expand($data['packages'][$package])`
+
 ```bash
 # Make sure the composer/metadata-minifer package is installed:
 composer require composer/metadata-minifier
@@ -22,6 +32,8 @@ $package = 'acme/package';
 // You can create a token in your Organization settings > Authentication Tokens
 $token = 'packagist_ort_..........'; 
 
+// The p2/$vendor/$package.json endpoint contains only tagged releases. If you want to fetch information about branches (i.e. dev versions) 
+// you need to use p2/$vendor/$package~dev.json.
 $apiUrl = sprintf('https://repo.packagist.com/%s/p2/%s.json', $organization, $package); 
 
 $ch = curl_init($apiUrl);