Merge pull request #69 from adorableio/document_and_clean_up

Documentation and cleanup

Author: itsthatguy

README.md

@@ -2,64 +2,80 @@
 [![Build Status](https://travis-ci.org/adorableio/avatars-api.svg?branch=master)](https://travis-ci.org/adorableio/avatars-api?branch=master)
 
 ## What is it?
+This repository contains the [express middleware](https://expressjs.com/en/guide/using-middleware.html#middleware.router) that can be used to host your own avatars service!
 
-#### What are avatars?
-Avatars are earthly creatures that serve as proxies for gods.
-In the web world, they just represent people, and they're usually small images. 
+Check out [our website](http://avatars.adorable.io/) for more info on (and an interactive demo of) what this service does.
 
-Some use photographs of themselves as their avatar. Some people use caricatures of themselves. Others pick their favorite superhero. The sky's the limit.
-
-#### What's an avatar _service_?
-It answers the question "What is this user's avatar?"
-In this way, it provides a consistent representation of that user.
-Across _all_ websites that use that service. Pretty cool, right?
-
-But what if you haven't uploaded your image to that service?
-Then you get a really boring, gray silhouette.
-
-#### So what's the Adorable Avatars service?
-It's an interface to a better universe. With a simple route, your face will be filled with consistently-linked avatar glory!
-
-Huh? _Consistently-linked avatar glory?_
+## How do I use it?
+First, you'll need to install the package:
 
-Whenever you make a request to Adorable Avatars, using an identifier like "[email protected]," we give you an image for you to use on your page.
-Most importantly, it's the same image! Every. Single. Time.
+```bash
+npm install adorable-avatars --save
+```
 
-## Why would I use it?
-What if you're developing a feature like member lists or profiles, but you don't have any images to use?
-Just give us your user's identifier and we'll give you their avatar image!
-That's it.
+Then, use the router middleware within your application:
 
-Already have avatars implemented in your application?
-Use Adorable Avatars as a fallback and get rid of those gray silhouettes!
+```js
+// your_server.js
+var express = require('express');
+var avatarsMiddleware = require('adorable-avatars');
 
-## How do I use it?
-Here's a quick example in Haml:
-```haml
-.user
-  %img.avatar(src="http://api.adorable.io/avatar/#{user.name}")
+var myApp = express();
+myApp.use('/myAvatars', avatarsMiddleware);
 ```
 
-### Requesting an Avatar
-The most basic request is of the following form:
+That's it! Your server now includes the avatars endpoints!
+
+### Endpoints
+Assuming your server lives at `myserver.com`, and you've configured the middleware as above, you now have the following endpoints:
+
+* `myserver.com/myAvatars/:id`
+    * returns an avatar for the provided `id`.
+    * `id` can be anything (email, username, md5 hash, as long as it's a valid URI)
+    * defaults to 400px
+* `myserver.com/myAvatars/:size/:id`
+    * returns an avatar for the provided `id` at the specified `size`
+    * size cannot exceed 400px
+* `myserver.com/myAvatars/face/:eyes/:nose/:mouth/:color`
+    * Allows you to generate a custom avatar from the specified parts and color
+    * e.g. `myserver.com/myAvatars/face/eyes1/nose2/mouth4/DEADBF`
+* `myserver.com/myAvatars/list`
+    * returns JSON of all valid parts for the custom endpoint above
+
+## Development
+If you're developing locally, you'll first need to bootstrap (assumes [nvm](https://github.com/creationix/nvm)):
+
+```bash
+# use correct node version
+nvm use
+
+# install dependencies
+npm install
+```
 
-    http://api.adorable.io/avatar/<identifier>
+Then, there are several npm scripts that will be useful:
 
-Where `identifier` is the unique identifier for your user (name, email, md5, etc.).
-This will serve the image in its default size.
+```bash
+# run the unit tests
+npm run test
 
-To request an avatar with specific size, use the following form:
+# run a dev server
+npm run start
 
-    http://api.adorable.io/avatar/<size>/<identifier>
+# run both a dev server and eslint
+npm run dev
 
-So, if you want your friend Bob's avatar, with a height and width of 200px, the URL would be:
+# compile the application
+npm run build
 
-    http://api.adorable.io/avatar/200/bob
+# run the compiled server
+npm run start:prod
+```
 
 ## Contributing
 
 Please read the [contributors' guide](CONTRIBUTING.md)
 
 ## Open-source Contributors
 
-* [missingdink](https://twitter.com/missingdink): Illustrated the very first avatars! [/avatar/](http://api.adorable.io/avatar/hi_mom)
+* [missingdink](https://twitter.com/missingdink): Illustrated the very first avatars! [Check them out!](http://api.adorable.io/avatar/hi_mom)