NAV Navbar
javascript
  • Introduction
  • Development
  • Installation
  • Authentication
  • Endpoints Summary
  • Users
  • Groups
  • Errors

    • Introduction

    Welcome to the PostIt API - A RESTful web service that allow users create accounts, create groups, add users to groups and post messages to created groups. The Postit API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use JSON Web Tokens (JWT) for authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors. this documentation will get you started on how you can easily consume this API. To consume this API, your stack should definitely be Javascript as we are yet to cover other languages. You can view code examples in the dark area to the right.

    Base API Endpoint

    https://postit-app-ralph.herokuapp.com/api/v1

    Development

    PostIt application was built with Node.js running express server. Postgres is the database used for the application and sequelize is the ORM used for connecting to the database.

    Installation

    To test out the endpoints in this API documentation, you need to set up your working environment locally. Follow the steps below to get you started. First, get Node.js v6.11.0 or later installed in your machine Ensure you have postgres installed also. Clone the github repo and run this command in your terminal, git clone https://github.com/ludralph/PostIt-Raphael-Etim.git. After cloning, run the command cd PostIt-Raphael-Etim to be in the project directory. Setup your database url in the .env file. Also run npm install to install all the npm package dependencies. Finally, to get the app running, start up the server with the command npm start.

    Authentication

    PostIt uses (username and password) fields to allow users access to the API protected routes. On registering or login, a token is generated.

    PostIt expects for the token to be included in all API requests to the server in a header that looks like the following:

    Authorization: token.

    Some endpoints (routes) in this API are protected. They require an access token (x-auth) in the request headers. You can get this token when you signup as a new user or login as existing user.

    To authorize requests to protected endpoints, set the x-auth token in the request header like this:

    {
  "x-auth":"YOUR_AUTH_KEY"
}

    Endpoints Summary

    Base Endpoint: https://postit-app-ralph.herokuapp.com/api/v1

    The endpoints for the listed routes should be appended to the base endpoint to get the full endpoint.

    User Routes

    Feature Request type Endpoint
    Sign up POST '/signup'
    Sign in POST '/signin'
    Get User groups GET '/user/:userId/groups'
    Search Users GET '/search/users'

    Recovery Routes

    Feature Request type Endpoint
    Forgot Password PUT '/forgotpassword'
    Reset Passwprd PUT '/resetpassword/:token'

    Group Routes

    Feature Request type Endpoint
    Create new Group POST '/group'
    Add user to Group POST '/group/:groupId/user'
    Get Group Users GET '/group/:groupId/users'
    Post New Message POST '/group/:groupId/message'
    Get Group Messages GET '/group/:groupId/messages'

    Users

    To use the API, you would have to signup as a user. Users can create groups, search other users, add them to their groups and send messages in groups to which they belong.

    Signup user

    This endpoint allows new users create accounts and access protected routes. If the request is successful, the response body would contain a message that welcomes the new user, and a user object that contains user data. This user object contains:

    Request Parameters

    Parameter Description
    username required
    email required
    password required

    Response Parameters

    Parameter Description
    message A descriptive notification of the outcome of the request
    user An object that contains the id, name and email of the user
    token The jwt token returned from the server that will be used to set the x-auth token in the request header

    Sample Request

    {
  "username":"johndoe",
  "email":"johndoe@gmail.com",
  "password":"mypassword"
}

    Sample Response Body

    {
    "message": "Signup Successful!",
    "user": {
        "id": 7,
        "name": "johndoe",
        "email": "johndoe@gmail.com"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjo3LCJuYW1lIjoib2xlb2xlb2xlIiwiZW1haWwiOiJvbGVvbGVvbGVAZ21haWwuY29tIn0sImlhdCI6MTUxMzI1NDkwMSwiZXhwIjoxNTEzMzQxMzAxfQ.JxCIhtDH72ctdKZBYJgE-Q2Aa6InKrAWlAgT82UqkFo"
}

    Request

    Response

    Signin user

    This endpoint allows existing users signin with the same credentials with which they created their accounts. The signin process returns an x-auth token in the header which identifies and authorizes the user to access other endpoints that require authentication. It returns a message welcoming the user, and a user object with the same fields as in the Signup response.

    Request Parameters

    Parameter Description
    username required
    password required

    Response Parameters

    Parameter Description
    message A descriptive notification of the outcome of the request
    user An object that contains the id, name and email of the user
    token The jwt token returned from the server that will be used to set the x-auth token in the request header

    Sample Request

    {
  "username":"johndoe",
  "password":"mypassword"
}

    Sample Response Body

    {
    "message": "Signin successful!",
    "user": {
        "id": 7,
        "name": "johndoe",
        "email": "johndoe@gmail.com"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjo3LCJuYW1lIjoib2xlb2xlb2xlIiwiZW1haWwiOiJvbGVvbGVvbGVAZ21haWwuY29tIn0sImlhdCI6MTUxMzI2MTIwOCwiZXhwIjoxNTEzMzQ3NjA4fQ.60OV2dUqiVCFsBalsbPHjnE9sKSS2JNxgirZeWfRN9k"
}

    Request

    Response

    Get groups a user belongs to

    This endpoint retrieves a list of groups the user belongs to. It requires authentication.

    Response Parameters

    Parameter Description
    id An integer value that represnts the group id
    name The name of the group the user belongs to
    createdAt Time the user record was created in the database.
    updatedAt Last time the user record was modified.

    Sample Response Body

    [
    {
        "id": 16,
        "name": "man united",
        "createdAt": "2017-12-14T14:37:02.792Z",
        "updatedAt": "2017-12-14T14:37:02.792Z"
    },
    {
        "id": 17,
        "name": "Real Madrid",
        "createdAt": "2017-12-14T14:37:26.754Z",
        "updatedAt": "2017-12-14T14:37:26.754Z"
    },
    {
        "id": 18,
        "name": "Bayern Munich",
        "createdAt": "2017-12-14T14:37:53.875Z",
        "updatedAt": "2017-12-14T14:37:53.875Z"
    }
]

    Request

    Response

    Search Users

    This endpoint searches for users that have registered on the application. It returns a paginated list of users. It requires authentication.

    Query Parameters

    Parameter Default Description
    searchTerm "" search query
    group omit users from this group
    limit 10 sets the limit
    offset 0 sets the offset

    Sample Response Body

    {
    "users": [
        {
            "id": 6,
            "email": "raphaelumoh@yahoo.com",
            "username": "raphaelumoh",
            "createdAt": "2017-12-11T15:35:19.468Z",
            "updatedAt": "2017-12-11T15:41:48.047Z"
        },
        {
            "id": 1,
            "email": "raphaelumoh@gmail.com",
            "username": "raphael",
            "createdAt": "2017-11-30T10:59:47.473Z",
            "updatedAt": "2017-11-30T10:59:47.473Z"
        }
    ],
    "pagination": {
        "page": 1,
        "pageCount": 1,
        "pageSize": 2,
        "totalCount": 2
    }
}

    Request

    Response

    Forgot Password

    This endpoint sends user's email containing the link to help them reset their password.

    Parameter Description
    email User's email address

    Sample Request

    {
  "email":"johndoe@gmail.com"
}

    Sample Response Body

    {
    "message": "An email has been sent to johndoe@gmail.com with further instructions."
}

    Request

    Response

    Reset Password

    Users who have gotten a reset email, can change their passwords, using the reset link as authentication. When making requests to this endpoint, simply copy the reset hash sent in the reset mail and attach to the (token) request pararmeter of this endpoint. This reset hash expires after a six hours and can only be used once.

    Parameter Description
    password User's password

    Sample Request

    {
  "password":"updatedpassword"
}

    Sample Response Body

    {
    "message": "Password Reset Successful"
}

    Request

    Response

    Groups

    Communications in PostIt takes place in groups.

    Create Groups

    A registered user can create a new group with this endpoint

    Request Parameters

    Parameter Description
    name required

    Response Parameters

    Parameter Description
    message A descriptive notification of the outcome of the request
    group An object that contains the id, name, createdAt and UpdatedAt properties for the group

    Sample Request

    {
  "name":"man united",

}

    Sample Response Body

    {
  "message": "Group Created Successfully",
  "group": {
    "id": 1,
    "name": "Man United",
    "updatedAt": "2017-12-14T16:54:09.951Z",
    "createdAt": "2017-12-14T16:54:09.951Z"
  }
}

    Request

    Response

    Add User to Groups

    Registered Users can be added to groups

    Request Parameters

    Parameter Description
    userId required

    Response Parameters

    Parameter Description
    message A descriptive notification of the outcome of the request

    Sample Request

    {
  "userId": 1
}

    Sample Response Body

    {
  "message": "User Added Successfully"
}

    Request

    Response

    Get Group Users

    We can retrieve a list of all users belonging to a particular group

    Sample Response Body

    [
    {
        "id": 7,
        "email": "johndoe@gmail.com",
        "username": "johndoe",
        "createdAt": "2017-12-14T12:34:59.991Z",
        "updatedAt": "2017-12-14T12:34:59.991Z"
    },
    {
        "id": 1,
        "email": "raphaelumoh@gmail.com",
        "username": "raphael",
        "createdAt": "2017-11-30T10:59:47.473Z",
        "updatedAt": "2017-12-14T16:03:02.432Z"
    }
]

    Request

    Response

    Add User to Groups

    Registered Users can be added to groups

    Request Parameters

    Parameter Description
    userId required

    Response Parameters

    Parameter Description
    message A descriptive notification of the outcome of the request

    Sample Request

    {
  "userId": 1
}

    Sample Response Body

    {
  "message": "User Added Successfully"
}

    Request

    Response

    Post Message

    We can post a message to a particular group

    Request Parameters

    Parameter Description
    content required
    priority required

    Sample Request

    {
  "content": "Hello Africa",
  "priority", "Normal"
}

    Sample Response Body

    {
    "message": {
        "id": 10,
        "senderId": 7,
        "content": "Hello Africa",
        "priority": "Normal",
        "groupId": 16,
        "updatedAt": "2017-12-15T09:32:22.422Z",
        "createdAt": "2017-12-15T09:32:22.422Z",
        "User": {
            "username": "johndoe"
        }
    }
}

    Request

    Response

    Get Messages

    We can retrieve a list of messages that has been posted to a group.

    Sample Response Body

    [
    {
        "id": 10,
        "content": "Hello Africa",
        "priority": "Normal",
        "groupId": 16,
        "senderId": 7,
        "createdAt": "2017-12-15T09:32:22.422Z",
        "updatedAt": "2017-12-15T09:32:22.422Z",
        "User": {
            "username": "johndoe"
        }
    },
    {
        "id": 11,
        "content": "Hello Africa",
        "priority": "Urgent",
        "groupId": 16,
        "senderId": 7,
        "createdAt": "2017-12-15T09:34:27.871Z",
        "updatedAt": "2017-12-15T09:34:27.871Z",
        "User": {
            "username": "johndoe"
        }
    }
]

    Request

    Response

    Errors

    The PostIt API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is not in the right syntax.
    401 Unauthorized -- You are not authenticated.
    403 Forbidden -- You are prohibited from accessing that resource.
    404 Not Found -- Your resource could not be found.
    409 Conflict -- Your request has a conflict.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    javascript