NAV Navbar
javascript
  • DocGenie API Documentation
  • Users
  • Documents
  • Roles

    • DocGenie API Documentation

    Introduction

    Docgenie API contains several end-points that allows users to create, edit, retrieve and delete documents. It also sets access privileges so only authorized users can perform certain operations. That is, only users in a particular role can view role-access documents, while only the creator of a document has the right to delete or edit it.

    Development

    The application was developed with NodeJs and Express is used for routing. The Postgres database was used with sequelize as the ORM.

    Installation

    Follow the steps below to setup a local development environment. First ensure you have Postgresql installed, and a version of Node.js equal or greater than v6.8.0.

    1. Clone the repository to your local machine: git clone https://github.com/andela-mharuna/DocGenie.git.
    2. Cd into the project directory: cd DocGenie
    3. Rename .env_example to .env and add the required environment variables.
    4. Install project dependencies npm install
    5. Start the express server in development mode: npm run start:dev.

    API Summary

    Users

    EndPoint Functionality
    POST /auth/api/v1/users/login Logs in a user.
    POST /api/v1/users/logout Logs out a user.
    POST /auth/api/v1/users Creates a new user(Sign up).
    GET /api/v1/users Gets all registered users (available only to the Admin).
    GET /api/v1/users/:id Finds a particular user by his/her id.
    PUT /api/v1/users/:id Updates a user's attributes based on the id specified (available only to the profile owner or admin).
    DELETE /api/v1/users/:id Deletes a user (available only to the profile owner).
    GET /api/v1/users/:id/documents Gets all documents belonging to a particular user.

    Documents

    EndPoint Functionality
    POST /api/v1/documents Creates a new document.
    GET /api/v1/documents Gets all documents.
    GET /api/v1/documents/:id Find a particular document by it's id.
    PUT /api/v1/documents/:id Updates a document attributes. (available only to the owner)
    DELETE /api/v1/documents/:id Delete a particular document. (available only to the document creator)
    GET /api/v1/search/documents/?searchKey=${query} Get all documents with title or content containing the search query

    Roles (available only to the Admin)

    EndPoint Functionality
    GET /api/v1/roles Get all created Roles.
    POST /api/v1/roles Create a new Role.
    DELETE /api/v1/roles/:id Delete a Role.

    Users

    List All Users

    Sample JSON structured response:

    {
  "users": [
      {
          "id": 12,
          "username": "Tolu",
          "fullname": "Tolu Afobs",
          "roleId": 2,
          "email": "tolu@gmail.com"
      },
      {
          "id": 11,
          "username": "biodun",
          "fullname": "biodun",
          "roleId": 2,
          "email": "biodun@gmail.com"
      },
      {
          "id": 8,
          "username": "Rob",
          "fullname": "Robert Ludlum",
          "roleId": 2,
          "email": "robert@robert.com"
      },
      {
          "id": 7,
          "username": "Johnie",
          "fullname": "John Grisham",
          "roleId": 2,
          "email": "john@grisham.com"
      },
      {
          "id": 6,
          "username": "Dorian",
          "fullname": "Dorian Gray",
          "roleId": 2,
          "email": "dorian@gray.com"
      },
      {
          "id": 5,
          "username": "Max",
          "fullname": "Gruocho",
          "roleId": 2,
          "email": "max@max.com"
      }
  ],
  "pagination": {
      "totalCount": 9,
      "pages": 2,
      "currentPage": 1,
      "pageSize": 6
  }
}

    Request

    Query Parameters

    Parameter Default Description
    limit 6 Sets the limit.
    offset 0 Sets the offset.

    Response

    Create User

    Request:

    {
  "username": "doro",
  "fullname": "doro bucci",
  "email": "doro@bucci.com",
  "password": "dorobucci",
  "confirmPassword": "dorobucci",
}

    Sample JSON structured response:

    {
    "message": "Signed up successfully",
    "user": {
        "id": 5,
        "username": "doro",
        "fullname": "doro bucci",
        "roleId": 2,
        "email": "doro@bucci.com"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVJZCI6MSwiaWF0IjoxNTAyMTAwMzA5LCJleHAiOjE1MDIxODY3MDl9.vzMK6Mr7cLr7rk5mXF5KeRXlJn913XBJXQjaOGJEiXo"
}

    Request

    Response

    Get User

    Sample JSON structured response:

    {
  "id": 4,
  "username": "Mikail",
  "fullname": "Mikail Stanislaski",
  "roleId": 2,
  "email": "mikahil.stanislaski@gmail.com",
}

    Request

    Response

    Edit User

    Request:

    {
  "username": "mikhy",
}

    Sample JSON structured response:

    {
  "id": 4,
  "username": "mikhy",
  "fullname": "Mikail Stanislaski",
  "email": "mikahil.stanislaski@gmail.com",
  "roleId": 2,
}

    Request

    Response

    Delete User

    Sample JSON structured response:

    {
  "message": "User deleted successfully"
}

    Request

    Response

    Login User

    Request:

    {
  "email": "tolu@gmail.com",
  "password": "afolabi"
}

    Sample JSON structured response:

    {
    "message": "Signed in successfully",
    "user": {
        "id": 1,
        "username": "tolu",
        "fullname": "tolu afobs",
        "roleId": 1,
        "email": "tolu@gmail.com"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVJZCI6MSwiaWF0IjoxNTAyMTAwMzA5LCJleHAiOjE1MDIxODY3MDl9.vzMK6Mr7cLr7rk5mXF5KeRXlJn913XBJXQjaOGJEiXo"
}

    Request

    Response

    Logout User

    Sample JSON structured response:

    {
  "message": "Successfully logged out"
}

    Request

    Response

    List User Documents

    Sample JSON structured response:

    [
  {
    "id": 1,
    "title": "Hello",
    "content": "It's me!",
    "access": 0,
    "userId": 1,
    "createdAt": "2017-05-28T22:19:08.870Z",
    "updatedAt": "2017-05-28T22:58:17.249Z",
    "user": {
      "username": "admin",
      "roleId": 1,
      "email": "admin@gmail.com",
      "fullname": "admin"
    }
  }
]

    Request

    Response

    Search Users

    Sample JSON structured response:

    {
  "users": [
      {
          "id": 12,
          "username": "Tolu",
          "fullname": "Tolu Afobs",
          "roleId": 2,
          "email": "tolu@gmail.com"
      },
      {
          "id": 11,
          "username": "biodun",
          "fullname": "biodun",
          "roleId": 2,
          "email": "biodun@gmail.com"
      },
      {
          "id": 8,
          "username": "Rob",
          "fullname": "Robert Ludlum",
          "roleId": 2,
          "email": "robert@robert.com"
      },
  ],
  "pagination": {
      "totalCount": 9,
      "pages": 2,
      "currentPage": 1,
      "pageSize": 6
  }
}

    Request

    Query Parameters

    Parameter Default Description
    searchKey "" Search query.

    Response

    Documents

    List All Documents

    Sample JSON structured response:

    {
  "documents": [
      {
          "id": 15,
          "userId": 1,
          "title": "Biodun's Dilemma",
          "access": 0,
          "content": "So, what will I eat for breakfast now that there's an election going on????",
          "createdAt": "2017-07-22T06:53:06.520Z",
          "updatedAt": "2017-07-22T06:53:06.520Z",
          "user": {
              "id": 1,
              "username": "admin",
              "roleId": 1,
              "fullname": "admin",
              "email": "admin@gmail.com"
          }
      },
      {
          "id": 14,
          "userId": 1,
          "title": "Sunday",
          "access": 1,
          "content": "First document edited",
          "createdAt": "2017-07-22T06:50:11.150Z",
          "updatedAt": "2017-07-23T15:03:56.047Z",
          "user": {
              "id": 1,
              "username": "admin",
              "roleId": 1,
              "fullname": "admin",
              "email": "admin@gmail.com"
          }
      },
      {
          "id": 12,
          "userId": 4,
          "title": "Nath's role document",
          "access": 2,
          "content": "Role document by nathan!!",
          "createdAt": "2017-07-21T12:58:33.691Z",
          "updatedAt": "2017-07-21T12:58:33.691Z",
          "user": {
              "id": 4,
              "username": "nathan",
              "roleId": 2,
              "fullname": "nathan",
              "email": "nathan@gmail.com"
          }
      },
  ],
  "pagination": {
      "totalCount": 7,
      "pages": 2,
      "currentPage": 1,
      "pageSize": 6
  }
}

    Request

    Query Parameters

    Parameter Default Description
    limit 6 Sets the limit.
    offset 0 Sets the offset.

    Response

    Create Document

    Request:

    {
  "title": "Chester",
  "content": "I'm so high, I can hear heaven. Oh, but Heaven can't hear me",
  "access": 2
}

    Sample JSON structured response:

    {
  "id": 3,
  "title": "Hello",
  "content": "Hello, It's me",
  "access": 0,
  "userId": 1,
  "createdAt": "2017-05-28T22:43:37.097Z",
  "updatedAt": "2017-05-28T22:43:37.097Z",
  "user": {
    "id": 2,
    "username": "admin",
    "fullname": "admin",
    "email": "admin",
    "roleId": 1
  },
}

    Request

    Response

    Get Document

    Sample JSON structured response:

    {
  "id": 6,
  "title": "Hello",
  "content": `Hello, It's me`,
  "access": 2,
  "userId": 3,
  "createdAt": "2017-05-28T22:19:08.870Z",
  "updatedAt": "2017-05-28T22:19:08.871Z",
  "user": {
    "id": 2,
    "username": "funms",
    "fullname": "funmi",
    "email": "funms@gmail.com",
    "roleId": 3
  }
}

    Request

    Response

    Edit Document

    Request:

    {
  "content": "What's new?"
}

    Sample JSON structured response:

    {
  "id": 3,
  "title": "Hello",
  "content": "What's new?",
  "access": 0,
  "userId": 1,
  "createdAt": "2017-05-28T22:43:37.097Z",
  "updatedAt": "2017-05-28T22:43:37.097Z",
  "user": {
    "id": 2,
    "username": "admin",
    "fullname": "admin",
    "email": "admin@gmail.com",
    "roleId": 1
  },
}

    Request

    Response

    Delete Document

    Sample JSON structured response:

    {
  "message": "Document deleted successfully"
}

    Request

    Response

    Search Documents

    Sample JSON structured response:

    {
  "documents": [
      {
      "id": 2,
      "title": "Saruman's Words",
      "content": `The hour is late and Gandalf the Grey comes to
      Isengard seeking my counsel...`,
      "access": -1,
      "userId": 2,
      "createdAt": "2017-05-28T22:19:08.871Z",
      "updatedAt": "2017-05-28T22:19:08.871Z",
      "user": {
        "id": 2,
        "username": "elf",
        "fullname": "arwen",
        "email": "arwen@aragon.com",
        "roleId": 2
      }
    },
    {
      "id": 1,
      "title": "Glory",
      "content": `When the glory comes, it will be ours, oh it will be ours,
      One day, when the war is won, we will be sure...`,
      "access": 0,
      "userId": 1,
      "createdAt": "2017-05-28T22:19:08.870Z",
      "updatedAt": "2017-05-28T22:19:08.871Z",
      "user": {
        "id": 3,
        "username": "sara",
        "fullname": "sara",
        "email": "sara@gmail.com",
        "roleId": 1
      }
    }
  ],
  "pagination": {
      "totalCount": 9,
      "pages": 2,
      "currentPage": 1,
      "pageSize": 6
  }
}

    Request

    Query Parameters

    Parameter Default Description
    searchKey "" Search query.

    Response

    Roles

    List All Roles

    Sample JSON structured response:

    [
  {
    "id": 1,
    "title": "admin"
  },
  {
    "id": 2,
    "title": "user"
  }
]

    Request

    Response

    Create Role

    Request:

    {
  "title": "guest",
}

    Sample JSON structured response:

    {
  "id": 3,
  "title": "guest",
}

    Request

    Response

    Delete Role

    Sample JSON structured response:

    {
  "message": "Role deleted successfully"
}

    Request

    Response

    javascript