package.json

{
  "name": "haypeaeye",
  "version": "0.5.8",
  "description": "Library for Express that lets you easily create APIs that self document and validate",
  "main": "haypeaeye.js",
  "repository": {
    "type": "git",
    "url": "git://github.com/darylrowland/haypeaeye.git"
  },
  "keywords": [
    "api",
    "express",
    "docs"
  ],
  "author": {
    "name": "Daryl Rowland",
    "email": "daryl@cloudyclear.com"
  },
  "license": "MIT",
  "dependencies": {
    "moment": "*",
    "request": "*"
  },
  "readme": "haypeaeye\n=========\n\nNodeJS Express API Library for creating APIs that self document and validate. The motivation behind haypeaeye was that I hated the idea of writing + commenting an API library in code and then having to write up the API again in a completely different place. This ultimately leads to inconsistencies between your code and your documentation... haypeaeye fixes this.\n\nNote: this is just the beginnings of the documentation, more will be added soon.\n\nhaypeaeye works alongside Express, and provides:\n* a way to easily define API endpoints WITH documentation\n* additional validation of parameters (e.g. of the parameter types you are passing into your API method)\n* an auto-generated documentation site with a console to try things out\n* a way to hook in to your existing authentication methods (for api methods that need to be protected)\n* utility methods for returning success or error statuses + data easily\n* NEW utility method for returning a video stream (to be displayed in a HTML5 video tag)\n\n\n### Getting Started\nIn your app.js: `var haypeaeye = require('haypeaeye')`\n\nThen add the following code snippet to set some initial settings:\n\n```\n// Haypeaeye Setup\nhaypeaeye.setSettings({\n    authenticatorMethod: function(req, callback) {\n        // Set this method to return if you want to provide a way of authenticating some API calls\n        // The callback should return callback(user)\n        // If there is no authorised user, the callback should be callback(null)\n\n    },\n    authAttributes: [\n        {name: \"appKey\", description: \"Application key\", type: exports.String},\n        {name: \"appToken\", description: \"Application token (if applicable)\", type: exports.String},\n        {name: \"userToken\", description: \"User token (if applicable)\", type: exports.String}\n    ],\n    applicationName: \"Your application name\"\n});\n\n```\n\nFinally, add the following code snippet to your app.js file, so that haypeaeye can process all routes beginning with /api/\n\n```\napp.all(\"/api/*\", function(req, res, next) {\n    haypeaeye.handleRequest(req, res, next);\n});\n```\n\n### Defining API Routes\nYou define haypeaeye routes in a similar way as you would Express routes. You can place the route definitions either in the app.js file, or across multiple route files.\n\nHere is an example haypeaeye route definition:\n\n```\nhaypeaeye.addApiMethod(\n    \"/api/say/hello\", haypeaeye.GET,\n    \"Says hello to the specified user\",\n    {grouping: \"Greetings\", auth: haypeaeye.AUTH_NOT_REQUIRED},\n    [\n        {name: \"first_name\", type: haypeaeye.String, required: true, description: \"User's first name\"},\n    ],\n    function(req, res) {\n        haypeaeye.successResponse(res, {\"message\": \"Hello \" + req.query.first_name});\n    }\n);\n```\n\n#### Parameter types\nThe following parameter types are currently supported:\n* haypeaeye.String\n* haypeaeye.Number\n* haypeaeye.Date\n* haypeaeye.File - although see note below about adding a multipart middleware\n* haypeaeye.Enum - restricts input to an array of valid values that you define in the validValues parameter of your field definitions\n\n#### Response utility methods\nHaypeaeye provides some utility methods for returning standard responses from your methods. These are:\n\n* Success - for returning a success response, where jsonContent is the response you are returning\n        ```\n        haypeaeye.successResponse(res, jsonContent);\n        ```\n* Error - for returning an error response (500), where err is the response you are returning (JSON object)\n        ```\n        haypeaeye.successResponse(res, err);\n        ```\n\n* Success or error - makes it easy for you to return an error or success depending directly on a callback\n        ```\n        haypeaeye.successOrErrorResponse(res, err, successData);\n        ```\n\n* Unathourised - for indicating that the user does not have permission to do that\n        ```\n        haypeaeye.unauthorisedResponse(res, message);\n        ```\n        \nNote: you can also provide field level errors in your error response. To do this, ensure your err object is in the following format:\n\n```\nerr = {message: \"There was a pretty nasty error\", fieldErrors: [field: \"first_name\", message: \"You forgot your name\"]}\n```\n\n\n### Accessing API Docs\nhaypeaeye will automatically generate API documentation for you in HTML (and JSON) format. To access the HTML docs go to the following URL on your server:\n\n/api/docs/html\n\n\n### Note on File Uploads\nIf you want to be able to upload files to your server, you'll need to include an Express middleware module like 'connect-multiparty' in your main app.js file, an example is below:\n\n```\nvar multipart = require('connect-multiparty'); // For haypeaeye file uploads\nvar multipartMiddleware = multipart();\n```\n\nYou then need to modify your app.all route for haypeaeye as shown below:\n\n```\napp.all(\"/api/*\", multipartMiddleware function(req, res, next) {\n    haypeaeye.handleRequest(req, res, next);\n});\n```\n\nYou can then access your parameters via req.files.param_name\n\nIt is well worth cleaning up the temp files that are generated from uploads after you're done with them. Haypeaeye provides a utility method that does this for you (where req is the ExpressJS request object):\n\n```\nhaypeaeye.removeTempFiles(req);\n```\n\n### Streaming Video\nhaypeaeye now includes a utility method that allows you to return a video stream back as the response. To do this, you need to call the following method:\n\n```\nhaypeaeye.streamVideo(req, res, path, contentType);\n```\n\nWhere path is the full path to your video file and contentType is the content type of your video (defaults to 'video/mp4')\n\n\n",
  "readmeFilename": "README.md",
  "gitHead": "cf02f02e8da36be65a707c9048e83d371b4e2fb2",
  "bugs": {
    "url": "https://github.com/darylrowland/haypeaeye/issues"
  },
  "homepage": "https://github.com/darylrowland/haypeaeye",
  "_id": "haypeaeye@0.3.0",
  "scripts": {},
  "_shasum": "4a66fcb18843134e696964f78f2eb8ff52782dee",
  "_from": "haypeaeye@*"
}