README.md

Lecture 108 - API Endpoints and Introduction to Swagger

Outline

1. API Endpoints

API Endpoints

Namespaces

• Public - Anyone with API access
• Admin / Private - Internal use only (restricted, different CORS policy)

We will follow no namespace at this moment

• Article

  Get all articles

  Method: GET
  Access: Public
  Path: /articles?query=params
  Query:

  • page (default 1) - current page number
  • limit (default 10) - the number of objects should be returned
  • sortType (default desc) - the type of sort, it could be either asc or desc
  • sortBy (default updatedAt) - the property that will used to sort. It could be either updatedAt or title.
  • search - the search term to filter articles based on the titles.

  
  

  Response:

  • 200

    • article data
      • id
      • title
      • cover
      • author
        • id
        • name
      • timestamp
    • pagination
      • page
      • limit
      • nextPage
      • prevPage
      • totalPage
      • totalArticle
    • links
      • self
      • nextPage
      • prevPage
      • comments
      • author

  • 400

    • message

  • 500

    • message
  Create a new article

  Method: POST
  Access: Private
  Path:/articles
  Request Body:

  • article data
    • title
    • body
    • cover (optional)
    • status (default draft)

  
  

  Response:

  • 201

    • message
    • article
    • links
      • self
      • comments
      • author

  • 400

    • message

    • data (Array of error messages)

      • field
      • message

  • 401

    • message
  Get a single article

  Method: GET
  Access: Public
  Path: /articles/:id?query=params
  Query:

  • expand (default none) - possible values (author, comment)

  
  

  Response:

  • 201

    • data
      • id
      • title
      • cover
      • body
      • timestamp
      • author (optional)
      • comments (optional)
    • links

  • 404

    • message

  • 400

    • message
    • possible solution
  Update a book using PUT

  Method: PUT
  Access: Private
  Path: /articles/:id
  Request Body:

  • id (optional)
  • title
  • body
  • cover (optional)
  • status (default draft)

  
  

  Response:

  • 200 / 201

    • message
    • article data
    • links
      • self

  • 400

    • message
    • data (Array of error message)
      • field
      • message

  • 401

    • message
  Update an article using PATCH

  Method: PATCH
  Access: Private
  Path: /articles/:id
  Request Body:

  • title (optional)
  • body (optional)
  • cover (optional)
  • status (default draft) (optional)

  
  

  Response:

  • 200

    • message
    • article data
    • links
      • self

  • 404

    • message

  • 400

    • message
    • data (Array of error message)
      • field
      • message

  • 401

    • message
  Delete an article

  Method: DELETE
  Access: Private
  Path: /articles/:id
  Response:

  • 204
    • message
  • 404
    • message
  • 401
    • message
  Get all comments for a given article

  Method: GET
  Access: Private
  Path: /articles/:id/comments
  Query:

  • page (default 1) - current page number
  • limit (default 10) - the number of objects should be returned

  
  

  Response:

  • 200

    • comments data
    • body
    • timestamp
    • author
      • id
      • name
    • pagination
    • page
    • limit
    • nextPage
    • prevPage
    • totalPage
    • totalBook
    • links
    • self
    • article
    • author
    • nextPage
    • prevPage

  • 404

    • message
  Create a new comment for a given article

  Method: Post
  Access: Private
  Path: /articles/:id/comments
  Request Body:

  • body

  
  

  Response:

  • 201

    • message
    • comments data
      • body
      • timestamp

  • 404

    • message

  • 400

    • message
  Get author of the given article

  Method: GET
  Access: Public
  Path: /articles/:id/author
  Response:

  • 200

    • author data
      • name
      • email
    • links
      • self
      • article

  • 404

    • message

• Comment

  Get all comment

  Method: GET
  Access: Private
  Role: Admin, User
  Description: User can see a list of their comments and admin can see a list of all comments
  Path: /comments?query=params
  Query:

  • page (default 1) - current page number
  • limit (default 10) - the number of object should be returned
  • sortType (default desc) - the type of sort, it could be either asc or desc
  • sortBy (default updateAt) - the property that will used to sort. It could be either updatedAt or title.
  • postId - the id of the post

  
  

  Response:

  • 200

    • comment data
  Create a comment
  Update a comment
  Delete a comment

• User

  Get all users
  Get a single user
  Create an user
  Update an user
  Delete an user
  Change password

• Auth

  Create a new account

  Method: POST
  Access: Public
  Description: Create a new account
  Path: /auth/singup
  Request Body:

  • user data

    • name
    • email
    • password
    
    

  Response:

  • 201

    • code
    • message
    • data
      • access_token
    • links
      • self
      • singin

  • 400

    • code
    • error
    • data
      • field
      • message
  Signin to existing account

  Method: POST
  Access: Public
  Description: Singin to existing account
  Path: /auth/singin
  Request Body:

  • user data
    • email
    • password

  
  

  Response:

  • 200

    • code
    • message
    • data
      • access_token
    • links
      • self

  • 400

    • code
    • error
    • data
      • field
      • message