From 509bd78c8e014e382c8bd54891bbc80a5598974b Mon Sep 17 00:00:00 2001
From: jomo <github@jomo.tv>
Date: Mon, 24 Nov 2014 01:12:39 +0100
Subject: [PATCH] add docs for usernames + skins

---
 views/index.jade | 45 ++++++++++++++++++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 9 deletions(-)

diff --git a/views/index.jade b/views/index.jade
index f26e0cd..64a0223 100644
--- a/views/index.jade
+++ b/views/index.jade
@@ -11,30 +11,41 @@ block content
         hr
         h2 Documentation
 
-        h3 Endpoint
+        h3 Avatars
         p
           | Replace 
-          mark.green uuid
-          |  with a Mojang UUID to get the related head. All images are PNGs.
+          mark.green id
+          |  with a Mojang UUID or username to get the related head. All images are PNGs.
         .code
           | &lt;img src="#{domain}/avatars/
-          mark.green uuid
+          mark.green id
           | "&gt;
 
         h3 Parameters
         h4 size
         p The size of the image in pixels, 1 - 512. <br> Default is 160.
         h4 default
-        p The image to be returned when the uuid has no skin (404). <br> Valid options are 
+        p The image to be returned when the id has no skin (404). <br> Valid options are 
           a(href="/avatars/00000000000000000000000000000000?default=steve") steve
           |  or 
           a(href="/avatars/00000000000000000000000000000000?default=alex") alex
-          | .<br> The standard value is calculated based on the UUID (even = alex, odd = steve)
+          | .<br> The standard value is calculated based on the id (even = alex, odd = steve)
         h4 helm
         p Get an avatar with the second (helmet) layer applied. <br> The content of this parameter is ignored
 
+        h3 Skins
+        p You can also get the full skin file from name or id. <br>
+          | Replace 
+          mark.green id 
+          | with a Mojang UUID or username to get the related skin.
+          | You are redirected to the textures URL, or a 404 is returned.
+        .code
+          | &lt;img src="#{domain}/skins/
+          mark.green id
+          | "&gt;
+
         h3 HTTP headers
-        p Images will come with these HTTP headers, useful for debugging.
+        p Responses come with these HTTP headers, useful for debugging.
         h4 Response-Time
         p The time, in milliseconds, it took Crafatar to process the request.
         h4 X-Storage-Type
@@ -42,9 +53,19 @@ block content
           li <b>none</b>: No external requests. Cached: User has no skin.
           li <b>cached</b>: No external requests. Skin cached and stored locally.
           li <b>checked</b>: 1 external request. Skin cached, checked for updates, no skin downloaded.<br>
-          | This happens either when the user has no skin or it didn't change.
+          | This happens either when the user removed their skin or when it didn't change.
           li <b>downloaded</b>: 2 external requests. Skin changed or unknown, downloaded.
-          li <b>error</b>: This can happen, for example, when Mojang's servers are down. If possible, an outdated image will be served instead.
+          li <b>error</b>: This can happen, for example, when Mojang's servers are down.<br>
+          | If possible, an outdated image is be served instead.
+
+        h3 About usernames
+        p We strongly advise you to use UUIDs instead of usernames in production.
+        | Usernames are deprecated by Mojang and you should only use usernames for testing.<br>
+        | Invalid usernames are rejected and a 422 is returned.
+
+        h3 About UUIDs
+        p UUIDs may use the raw or dashed format.<br>
+        | Invalid UUIDs are rejected and a 422 is returned.
 
         h3 Examples
         p Get jeb_'s avatar, 160 × 160 pixels
@@ -53,6 +74,12 @@ block content
         .code &lt;img src="#{domain}/avatars/853c80ef3c3749fdaa49938b674adae6?size=64"&gt;
         p Get jeb_'s helmet avatar, 64 × 64 pixels
         .code &lt;img src="#{domain}/avatars/853c80ef3c3749fdaa49938b674adae6?size=64&amp;helm"&gt;
+        p Get jeb_'s avatar by username, 160 x 160 pixels
+        .code &lt;img src="#{domain}/avatars/jeb_"&gt;
+        p Get jeb_'s skin
+        .code &lt;img src="#{domain}/skins/853c80ef3c3749fdaa49938b674adae6"&gt;
+        p Get jeb_'s skin by username
+        .code &lt;img src="#{domain}/skins/jeb_"&gt;
       .col-md-2.center
         .sideface.redstone_sheep(title="redstone_sheep")
         .sideface.Jake0oo0(title="Jake0oo0")