Skip to content

Latest commit

 

History

History
382 lines (269 loc) · 9.38 KB

README.md

File metadata and controls

382 lines (269 loc) · 9.38 KB
Raw

Lernhow

Lernhow provides 5-step guides to knowledge, created by lerners for lerners. No more searching sprawling wikis for what you need. Avoid all the useless information. Come Lernhow.

Table of Contents

  1. Requirements
    1. Installing Dependencies
    2. Running the Server
  2. Deployment
  3. Documentation
  4. Roadmap
  5. Team
  6. Contributing

Development Requirements

  • Node 0.10.x
  • npm 2.x.x
  • MongoDB 2.6.x
  • Sass 3.4.x

Installing Dependencies

Install Node (bundled with npm) with Homebrew

brew install node

Install MongoDB with Homebrew

brew install mongodb

Install Sass (you will need Ruby)

gem install sass

Install Bower Globally

npm install -g bower

Install Project Dependencies

npm install
bower install

Running the Server

Use gulp to start the development server

gulp

You should now be able to preview your development site at http://localhost:8000

Deployment

Deploying to Heroku requires a Heroku account and the Heroku toolbelt installed — instructions here. Once you have the Heroku toolbelt and an account, proceed with the instructions below.

Log in to your account via the Heroku CLI

heroku login

Create a new Heroku app in the root folder of your project, optionally specifying a name for your app.

heroku create app-name

Set up your Heroku app to use this buildpack and the correct Node environment by running the following command:

heroku config:set BUILDPACK_URL=https://github.com/OceanOracles/heroku-buildpack-nodejs-gulp-bower-sass.git NODE_ENV=production

Add the MongoLab addon (this step will require a credit card on file in your Heroku account)

heroku addons:add mongolab

Check your production environment configuration variables to make sure it has a BUILDPACK_URL, NODE_ENV, and MONGOLAB_URI

heroku config

If your configuration variables looked correct, push your branch onto the master branch of your heroku remote

git push heroku <BRANCH_NAME>:master

Lernhow API Documentation

API Authentication

Lernhow uses JSON Web Tokens to authenticate requests to the API. When a client signs up or logs in, the client is given a web token, which is attached on every future request to the Lernhow API. The attached token allows the server to verify the authenticity of the client request. The token should be sent as an 'x-access-token' header with the client request.

Here is an example curl request to a protected endpoint:

curl "https://lernhow.herokuapp.com/api/protected-endpoint"
  -H "x-access-token: someridiculouslylongstringthatyoushouldputhere"

API Endpoints

The API currently serves three resources, mapped to URIs as follows:

  • User -> /api/users
  • Guide -> /api/guides
  • Step -> /api/steps

Users

Endpoint: /api/users

Signup a new user

HTTP request: POST /api/users/signup

HTTP response: a valid JSON web token and a unique userId of the following format:

{
  "token": "boomshakalakausertokensupercraycrayencryption",
  "userId": "somestringthatisunique"
}

Login a user with a valid account

HTTP request: POST /api/users/login

Note: the request body must send a valid username and password

HTTP response (successful login): a valid JSON web token and a unique userId of the following format:

{
  "token": "boomshakalakausertokensupercraycrayencryption",
  "userId": "somestringthatisunique"
}

HTTP response (error on login): a JSON error object of the following format:

{
  "status": "404",
  "message": "Some login-related error message"
}

Guides

Endpoint: /api/guides

Get all guides

HTTP request: GET /api/guides/

HTTP response: an array of JSON Guide objects of the following format:

[
  {
    "_id": "sdafljk29askdjf20",
    "title": "Some Witty Title",
    "userId": "asdlfkjweraksjdfashkbf",
    "author": "SomeUsername",
    "createdAt": "Date of resource creation",
    "updatedAt": "Date of last resource update"
  },
  {
    "_id": "jklljkhkjasdfjlk18",
    "title": "Some Witty Title 2",
    "userId": "lkljkkljhkhjasdfasdf",
    "author": "SomeUsername2",
    "createdAt": "Date of resource creation",
    "updatedAt": "Date of last resource update"
  },
  "..."
]

Create a new guide

HTTP request: POST /api/guides/

Note: the request body must send a title, and the request header must contain a valid 'x-access-token'.

HTTP response: a JSON representation of the newly created Guide:

{
  "_id": "sdafljk29askdjf20",
  "title": "Some Witty Title",
  "userId": "asdlfkjweraksjdfashkbf",
  "author": "SomeUsername",
  "createdAt": "Date of resource creation",
  "updatedAt": "Date of last resource update"
}

Get a specific guide

HTTP request: GET /api/guides/:guideId

Note: the request header must contain a valid 'x-access-token'.

HTTP response: a JSON representation of the requested Guide:

{
  "_id": "guideIdFromRequestUri",
  "title": "Some Witty Title",
  "userId": "asdlfkjweraksjdfashkbf",
  "author": "SomeUsername",
  "createdAt": "Date of resource creation",
  "updatedAt": "Date of last resource update"
}

Edit a specific guide

HTTP request: PUT /api/guides/:guideId

Note: the request body should send the data with which to update the resource, and the request header must contain a valid 'x-access-token' that matches the token of the resource creator.

HTTP response: a JSON representation of the recently edited Guide:

{
  "_id": "guideIdFromRequestUri",
  "title": "Some Even Wittier Title",
  "userId": "asdlfkjweraksjdfashkbf",
  "author": "SomeUsername",
  "createdAt": "Date of resource creation",
  "updatedAt": "Date of last resource update"
}

Delete specific guide

HTTP request: Delete /api/guides/:guideId

Note: the request header must contain a valid 'x-access-token' that matches the token of the resource creator.

HTTP response (if successful resource deletion): 204 status code

HTTP response (if unsuccessful resource deletion): 500 status code

Show a specific guide's 5 steps

HTTP request: GET /api/guides/:guideId/steps

Note: the request header must contain a valid 'x-access-token'.

HTTP response: a JSON representation of the requested Guide's 5 steps:

[
  {
    "_id": "someStepId",
    "stepNum": "1",
    "content": "Some really smart step content",
    "userId": "asdlfkjweraksjdfashkbf",
    "guideId": "guideIdFromRequestUri",
    "createdAt": "Date of resource creation",
    "updatedAt": "Date of last resource update"
  },
  {
    "_id": "someStepId2",
    "stepNum": "2",
    "content": "Some really smart step content 2",
    "userId": "asdlfkjweraksjdfashkbf",
    "guideId": "guideIdFromRequestUri",
    "createdAt": "Date of resource creation",
    "updatedAt": "Date of last resource update"
  },
  "... 5 total steps"
]

Steps

Endpoint: /api/steps

Create a new step

HTTP request: POST /api/steps/

Note: the request body must send content, and the request header must contain a valid 'x-access-token'.

HTTP response: a JSON representation of the newly created Step:

{
  "_id": "someStepId",
  "stepNum": "1",
  "content": "Some really smart step content",
  "userId": "asdlfkjweraksjdfashkbf",
  "guideId": "guideIdFromRequestUri",
  "createdAt": "Date of resource creation",
  "updatedAt": "Date of last resource update"
}

Get a specific step

HTTP request: POST /api/steps/:stepId

Note: the request header must contain a valid 'x-access-token'.

HTTP response: a JSON representation of the requested Step:

{
  "_id": "stepIdFromRequestUri",
  "title": "Some Witty Title",
  "userId": "asdlfkjweraksjdfashkbf",
  "author": "SomeUsername",
  "createdAt": "Date of resource creation",
  "updatedAt": "Date of last resource update"
}

Edit a specific step

HTTP request: PUT /api/steps/:stepId

Note: the request body should send the data with which to update the resource, and the request header must contain a valid 'x-access-token' that matches the token of the resource creator.

HTTP response: a JSON representation of the recently edited Step:

{
  "_id": "stepIdFromRequestUri",
  "title": "Some Witty Title Updated",
  "userId": "asdlfkjweraksjdfashkbf",
  "author": "SomeUsername",
  "createdAt": "Date of resource creation",
  "updatedAt": "Date of last resource update"
}

Product Roadmap

The product roadmap is managed through this repository's Issues — view the roadmap here.

Lernhow Team

  • Product Owner: Raghuvir Kasturi
  • Scrum Master: Eric Kennedy
  • Development Team: Clark Feusier

Contributing

We welcome contributions, but please read our contribution guidelines before submitting your work.