Giter Club home page Giter Club logo

2770's Introduction

<!DOCTYPE html>
<head>
    <meta charset=utf-8 />
    <link href="http://netdna.bootstrapcdn.com/bootstrap/3.0.0-rc2/css/bootstrap.min.css" rel="stylesheet">
    <script src="http://netdna.bootstrapcdn.com/bootstrap/3.0.0-rc2/js/bootstrap.min.js"></script>
    <title>REST API OAuth2 Readme</title>
</head>
<body class="container">
    
<h1>General</h1>
<p>
  This Application targets the Cloudspokes challenge described <a href="http://www.cloudspokes.com/challenges/2660">here</a>.
  It utilizes <a href="http://coffeescript.org/">CoffeeScript</a>, a language that compiles into Javascript.
  The Application provides basic CRUD functionality and OAuth2 authentication. It is using <a href="http://nodejs.org/">node</a> 
  with <a href="http://mcavage.me/node-restify/">restify</a> and can be easily deployed to <a href="http://heroku.com">heroku</a>.
</p>
<p>
    <a href="https://github.com/dresende/node-orm2">orm2</a> is used for database transactions, 
    <a href="https://github.com/domenic/restify-oauth2">restify-oauth2</a> provides basic OAuth2 functionality.
    <a href="https://github.com/aws/aws-sdk-js">aws-sdk</a>, the official nodejs SDK from Amazon, is used to access their services.
    <a href="https://github.com/soldair/node-qrcode">qrcode</a> provides the QR coding functionality.
</p>
<p>
  If you prefer Javascript over CoffeeScript you can use it aswell.
  You could for example create a new route "/foo" and create a corresponding "foo-controller.js" in the controllers directory.
</p>
<p>
    You can find a demo video of the application <a href="http://screencast.com/t/40VBwpFz5ij5">here</a> 
    and a video explaining the basic architecture <a href="http://screencast.com/t/gK19wn3a">here</a>.
    <br />
    postman.json provides some sample requests for 
    <a href="https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en">Postman</a>.
    <br />
    A demo version of the application has been <a href="http://fast-bayou-5446.herokuapp.com/">pushed to heroku</a>, 
    the demo version will wipe the database on each restart.
    <br />
    src/demos/qrcode.html provides a sample for the QR code generation (<a href="http://fast-bayou-5446.herokuapp.com/demos/qrcode.html">live</a>)
</p>

<h1>Configuration</h1>
<p>
  All Configuration is bundled in a single file, namely src/config.coffee.
  This list will explain the various options.
</p>
<ul>
    <li><b>require_accept_version</b> if set to true the HTTP client is forced to deliver the "Accept-Version" header</li>
    <li><b>server_name</b> the server name as it is provided to restify</li>
    <li><b>token_url</b> the path where clients can request a token</li>
    <li><b>auth_realm</b> the WWW-Authenticate realm send to the clients</li>
    <li><b>generator</b> default password/token generator</li>
    <li><b>qr_max_size</b> the max size for the data used to generate a QR code</li>
    <li><b>cache_qrcodes</b> if true then cache the results in the database</li>
    <li><b>database</b> all settings related directly to the postgres database
      <ul>
          <li><b>user</b> the name of the database user</li>
          <li><b>password</b> the password of the given user</li>
          <li><b>host</b> the database server</li>
          <li><b>port</b> port to use</li>
          <li><b>override_url</b> this can be set to ignore all above values and use a prepared url to connect, especially useful for heroku</li>
          <li><b>reset_tables</b> this will reset all required tables (tables are dropped and created afterwards), can be used to initialize the database</li>
      </ul>    
    </li>
    <li><b>s3</b> all settings related directly to the amazon s3 storage service
      <ul>
          <li><b>username</b> the name of the s3 user</li>
          <li><b>access_key_id</b> the given access key id for the s3 user</li>
          <li><b>secret_access_key</b> the secret access key for the s3 user</li>
          <li><b>bucket_name</b> the name of the bucket to upload the objects to</li>
          <li><b>use_private_urls</b> if true then objects will be private and a temporal URL to access them will be generated</li>
          <li><b>urls_expire_after</b> if using private URLs, this value defined the lifetime of the objects (in seconds)</li>
      </ul>    
    </li>
</ul>
* To obtain your Amazon credentials:
<ul>
    <li>Go to the service page.</li>
    <li>Hover over "My Account", and click on "Security Credentials".</li>
    <li>Scroll to the "Access credentials" section.</li>
    <li>Your access key is listed under "Access Key ID".</li>
    <li>Click the "Show" link under "Secret Access Key" to show your secret access key</li>
</ul>

<h1>Versioning and Routing</h1>
<p>
  This application is using restify and thus supports <a href="http://mcavage.me/node-restify/#Routing">route versioning</a>. 
  The server will report the version of the requested route in each response (see "Version" header). The client should supply an "Accept-Version" header.
  The version number must comply with <a href="http://semver.org/">semver</a> syntax.
</p>
<p>
  All routes are specified in routes.coffe, each route defines a hashmap with a correspondig controller (a requireJS module), 
  a version (defaults to 1.0.0) and handlers for at least one HTTP verb.
  Take a look at the routes.coffe file for examples.
</p>

<h1>Heroku Deployment</h1>
<p>
  For the QR code generation, the deployment at Heroku needs to use a BUILDPACK that supports the cairo package, used to draw the QR canvas.
  Heroku deployment also requires adding a postgres database first, and updating a single app config.
  Depending on your database you need to adjust the database connection settings in the config file, see <a href="https://devcenter.heroku.com/articles/nodejs#using-a-postgresql-database">heroku devcenter</a> for details.
  <h3>Typical Deployment Procedure</h3>
  <ol>
    <li>git clone [email protected]:cloudspokes/brivolabs-pi.git</li>
    <li>cd brivolabs-pi</li>
    <li>heroku apps:create pi-api-<b>$YOURNAME</b></li>
    <li>heroku config:add BUILDPACK_URL=git://github.com/mojodna/heroku-buildpack-nodejs.git#cairo</li>
    <li>heroku addons:add heroku-postgresql:dev</li>
    <li>heroku config</li>
    <li>update src/config.coffee: set database.override_url property with the correct “color” of postgres URL from heroku config (if different!)</li>
    <li>git commit -a -m “updated database URL”</li>
    <li>heroku config:set RESET_TABLES=true</li>
    <li>git push heroku master</li>
    <li>hit: http://pi-api-<b>$YOURNAME</b>.herokuapp.com/</li>
    <li>heroku config:unset RESET_TABLES</li>
    <li>done!</li>
  </ol>
</p>
</body>

2770's People

Contributors

gfhuertac avatar mcilroyc avatar

Watchers

avatar James Cloos avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.