endpoints.json

{
  "GET /api": {
    "description": "serves up a json representation of all the available endpoints of the api"
  },
  "GET /api/topics": {
    "description": "serves an array of all topics",
    "details": {
      "queries": [],
      "exampleResponses": {
        "200": {
          "topics": [{ "slug": "football", "description": "Footie!" }]
        },
        "404": {
          "description": "Returns an error message for invalid endpoint.",
          "exampleResponse": {
            "msg": "404 - Not Found: Endpoint does not exist"
          }
        }
      }
    }
  },
  "POST /api/topics": {
    "description": "creates a new topic with a unique slug and description.",
    "details": {
      "requestBody": {
        "slug": "string",
        "description": "string"
      },
      "exampleResponses": {
        "201": {
          "description": "Returns the newly created topic object.",
          "exampleResponse": {
            "topic": {
              "slug": "new-topic",
              "description": "A new topic"
            }
          }
        },
        "400": {
          "description": "Returns an error message when slug is empty.",
          "exampleResponse": {
            "msg": "400 - Bad Request: Slug or Description cannot be empty"
          }
        }
      }
    }
  },
  "GET /api/articles": {
    "description": "serves an array of all articles",
    "details": {
      "queries": ["author", "topic", "sort_by", "order", "limit", "page"],
      "queryDescriptions": {
        "author": "Filter articles by the username of the author",
        "topic": "Filter articles by the topic",
        "sort_by": "Sort articles by a valid column. Defaults to 'created_at'. Valid columns: article_id, title, author, body, topic, created_at, votes, comment_count",
        "order": "Specify 'asc' for ascending or 'desc' for descending order. Defaults to 'desc'",
        "limit": {
          "description": "limits the number of responses",
          "default": 10
        },
        "page": {
          "description": "page number",
          "default": 1
        }
      },
      "exampleQueries": [
        {
          "query": "?sort_by=created_at&order=asc",
          "description": "Sort articles by created_at in ascending order"
        },
        {
          "query": "?sort_by=votes&order=desc",
          "description": "Sort articles by votes in descending order"
        },
        {
          "query": "?topic='cooking'",
          "description": "Filter articles by the topic 'cooking'"
        },
        {
          "query": "?topic=cooking&sort_by=votes&order=asc",
          "description": "Filter articles by the topic 'cooking' and sort by votes in ascending order"
        }
      ],
      "exampleResponses": {
        "200": {
          "articles": [
            {
              "article_id": 33,
              "title": "Seafood substitutions are increasing",
              "topic": "cooking",
              "author": "weegembump",
              "body": "Text from the article..",
              "created_at": "2018-05-30T15:59:13.341Z",
              "votes": 0,
              "comment_count": 6
            }
          ],
          "total_count": 12
        },
        "404": {
          "description": "Returns an error message for non-existent topic.",
          "exampleResponse": {
            "msg": "404 - Not Found: Topic not found"
          }
        }
      }
    }
  },
  "POST /api/articles": {
    "description": "adds a new article and responds with the newly added article.",
    "details": {
      "requestBody": {
        "description": "The article to be added.",
        "example": {
          "author": "butter_bridge",
          "title": "New Article Title",
          "body": "This is the body of the new article.",
          "topic": "mitch",
          "article_img_url": "http://example.com/img.png"
        },
        "properties": {
          "author": {
            "type": "string",
            "description": "The username of the article's author."
          },
          "title": {
            "type": "string",
            "description": "The title of the article."
          },
          "body": {
            "type": "string",
            "description": "The content of the article."
          },
          "topic": {
            "type": "string",
            "description": "The topic of the article."
          },
          "article_img_url": {
            "type": "string",
            "description": "URL of the article's image. Defaults to a placeholder URL if not provided."
          }
        }
      },
      "exampleResponses": {
        "201": {
          "description": "Responds with the newly added article.",
          "article": {
            "article_id": 14,
            "author": "butter_bridge",
            "title": "New Article Title",
            "body": "This is the body of the new article.",
            "topic": "mitch",
            "article_img_url": "http://example.com/img.png",
            "votes": 0,
            "created_at": "2024-07-19T10:11:10.086Z",
            "comment_count": 0
          },
          "properties": {
            "article": {
              "type": "object",
              "properties": {
                "article_id": {
                  "type": "integer",
                  "description": "The unique identifier for the article."
                },
                "author": {
                  "type": "string",
                  "description": "The username of the article's author."
                },
                "title": {
                  "type": "string",
                  "description": "The title of the article."
                },
                "body": {
                  "type": "string",
                  "description": "The content of the article."
                },
                "topic": {
                  "type": "string",
                  "description": "The topic of the article."
                },
                "article_img_url": {
                  "type": "string",
                  "description": "URL of the article's image."
                },
                "votes": {
                  "type": "integer",
                  "description": "The number of votes for the article. Defaults to 0."
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The date and time when the article was created."
                },
                "comment_count": {
                  "type": "integer",
                  "description": "The number of comments on the article. Defaults to 0."
                }
              }
            }
          }
        },
        "errors": [
          {
            "status": 400,
            "description": "Returns an error message when required fields are missing.",
            "exampleResponse": {
              "msg": "400 - Bad Request: Missing required fields"
            }
          },
          {
            "status": 404,
            "description": "Returns an error message when author does not exist.",
            "exampleResponse": {
              "msg": "404 - Not Found: Article or User does not exist"
            }
          },
          {
            "status": 500,
            "description": "Returns an error message when unexpected error occurred.",
            "exampleResponse": {
              "msg": "Internal Server Error"
            }
          }
        ]
      }
    }
  },
  "GET /api/articles/:article_id": {
    "description": "serves an article object by its id",
    "details": {
      "queries": [],
      "exampleResponse": {
        "200": {
          "article_id": 1,
          "article_img_url": "https://images.pexels.com/photos/158651/news-newsletter-newspaper-information-158651.jpeg?w=700&h=700",
          "author": "butter_bridge",
          "body": "I find this existence challenging",
          "created_at": "2020-07-09T20:11:00.000Z",
          "title": "Living in the shadow of a great man",
          "topic": "mitch",
          "votes": 100,
          "comment_count": 11
        },
        "errors": [
          {
            "status": 400,
            "description": "Returns an error message for an invalid article_id.",
            "exampleResponse": {
              "msg": "400 - Bad Request: invalid_id"
            }
          },
          {
            "status": 404,
            "description": "Returns an error message for a non-existent article_id.",
            "exampleResponse": {
              "msg": "404 - Not Found: Article not found"
            }
          }
        ]
      }
    }
  },
  "PATCH /api/articles/:article_id": {
    "description": "Updates the vote count of an article by article_id",
    "details": {
      "requestBody": {
        "inc_votes": "an integer that indicates how much the votes property should be updated by"
      },
      "exampleRequest": {
        "inc_votes": 1
      },
      "exampleResponses": {
        "200": {
          "article": {
            "article_id": 1,
            "title": "Seafood substitutions are increasing",
            "topic": "cooking",
            "author": "weegembump",
            "body": "Text from the article...",
            "created_at": "2020-11-03T09:12:00.000Z",
            "votes": 1
          }
        },
        "errors": [
          {
            "status": 400,
            "description": "Returns an error message for an invalid article_id.",
            "exampleResponse": {
              "msg": "400 - Bad Request: invalid_id"
            }
          },
          {
            "status": 400,
            "description": "Returns an error message for an invalid inc_votes.",
            "exampleResponse": {
              "msg": "400 - Bad Request: inc_votes must be a number"
            }
          },
          {
            "status": 400,
            "description": "Returns an error message when inc_votes is missing in request body.",
            "exampleResponse": {
              "msg": "400 - Bad Request: inc_votes must be a number"
            }
          },
          {
            "status": 404,
            "description": "Returns an error message for non-existent article_id.",
            "exampleResponse": {
              "msg": "404 - Not Found: Article not found"
            }
          }
        ]
      }
    }
  },
  "DELETE /api/articles/:article_id": {
    "description": "deletes an article by its id",
    "details": {
      "exampleResponses": {
        "204": {
          "description": "404 - Not Found: Article not found."
        },
        "errors": [
          {
            "status": 400,
            "description": "Returns an error message for an invalid article_id.",
            "exampleResponse": {
              "msg": "400 - Bad Request: invalid_id"
            }
          },
          {
            "status": 404,
            "description": "Returns an error message if the article does not exist.",
            "exampleResponse": {
              "msg": "404 - Not Found: Article not found"
            }
          }
        ]
      }
    }
  },
  "GET /api/articles/:article_id/comments": {
    "description": "serves an array of comments for a given article_id",
    "details": {
      "queries": {
        "limit": "Limits the number of responses (defaults to 10)",
        "page": "Specifies the page at which to start (calculated using limit)"
      },
      "exampleResponses": {
        "200": {
          "comments": [
            {
              "comment_id": 31,
              "votes": 11,
              "created_at": "2020-09-26T00:17:16.000Z",
              "author": "weegembump",
              "body": "Oh, I've got compassion running out of my nose, pal! I'm the Sultan of Sentiment!",
              "article_id": 1
            },
            {
              "comment_id": 2,
              "votes": 14,
              "created_at": "2020-11-01T12:56:20.000Z",
              "author": "butter_bridge",
              "body": "The beautiful thing about treasure is that it exists. Got to find out what kind of sheets these are; not cotton, not rayon, silky.",
              "article_id": 1
            },
            {
              "comment_id": 3,
              "votes": 100,
              "created_at": "2020-03-05T16:46:20.000Z",
              "author": "icellusedkars",
              "body": "Replacing the quiet elegance of the dark suit and tie with the casual indifference of these muted earth tones is a form of fashion suicide, but, uh, call me crazy — onyou it works.",
              "article_id": 1
            }
          ],
          "total_count": 3
        },
        "errors": [
          {
            "status": 400,
            "description": "Returns an error message for an invalid article_id.",
            "exampleResponse": {
              "msg": "400 - Bad Request: invalid_id"
            }
          },
          {
            "status": 400,
            "description": "Returns an error message for an invalid query parameters.",
            "exampleResponse": {
              "msg": "400 - Bad Request: Invalid query parameters"
            }
          },
          {
            "status": 404,
            "description": "Returns an error message if the article does not exist.",
            "exampleResponse": {
              "msg": "404 - Not Found: Article not found"
            }
          }
        ]
      }
    }
  },
  "POST /api/articles/:article_id/comments": {
    "description": "adds a comment for the specified article ID",
    "details": {
      "requestBody": {
        "username": "string",
        "body": "string"
      },
      "exampleRequestBody": {
        "username": "butter_bridge",
        "body": "This is a new comment!"
      },
      "exampleResponse": {
        "comment_id": 14,
        "votes": 0,
        "created_at": "2024-07-16T00:00:00.000Z",
        "author": "butter_bridge",
        "body": "This is a new comment!",
        "article_id": 1
      }
    }
  },
  "GET /api/comments/:comment_id": {
    "description": "Retrieves a comment by its ID.",
    "details": {
      "queries": [],
      "exampleResponse": {
        "200": {
          "comments": {
            "comment_id": 1,
            "body": "Oh, I've got compassion running out of my nose, pal! I'm the Sultan of Sentiment!",
            "article_id": 9,
            "author": "butter_bridge",
            "votes": 16,
            "created_at": "2020-04-06T12:17:00.000Z"
          }
        }
      },
      "errorResponses": {
        "404": {
          "description": "Comment not found for the given comment_id",
          "exampleResponse": {
            "msg": "404 - Not Found: Comment not found"
          }
        },
        "400": {
          "description": "Invalid comment_id syntax",
          "exampleResponse": {
            "msg": "400 - Bad Request: invalid_id"
          }
        }
      }
    }
  },
  "PATCH /api/comments/:comment_id": {
    "description": "Updates the votes on a comment given the comment's comment_id. The request body should include `inc_votes` indicating how much to change the votes by.",
    "details": {
      "requestBody": {
        "inc_votes": "number"
      },
      "exampleRequestBody": {
        "inc_votes": 1
      },
      "exampleResponse": {
        "comment": {
          "comment_id": 1,
          "votes": 101,
          "created_at": "2020-03-28T00:10:20.000Z",
          "author": "butter_bridge",
          "body": "Oh, I've got compassion running out of my nose, pal! I'm the Sultan of Sentiment!",
          "article_id": 9
        }
      },
      "errorResponses": {
        "404": {
          "description": "Comment not found for the given comment_id",
          "exampleResponse": {
            "msg": "404 - Not Found: Comment not found"
          }
        },
        "400": {
          "description": "Bad Request. Invalid comment_id or inc_votes",
          "exampleResponse": {
            "msg": "400 - Bad Request: Invalid comment_id or inc_votes"
          }
        }
      }
    }
  },
  "DELETE /api/comments/:comment_id": {
    "description": "Deletes the given comment by comment_id",
    "details": {
      "queries": [],
      "exampleResponse": {
        "204": {
          "description": "The comment was successfully deleted. No content is returned."
        },
        "400": {
          "description": "Bad Request. Invalid comment_id."
        },
        "404": {
          "description": "Not Found. Comment not found."
        }
      },
      "example": {
        "request": {
          "method": "DELETE",
          "url": "/api/comments/1"
        },
        "response": {
          "status": 204
        }
      }
    }
  },
  "GET /api/users": {
    "description": "Retrieves a list of all users from the database. Each user object contains the username, name, and avatar URL of the user.",
    "details": {
      "queries": [],
      "exampleResponse": {
        "users": [
          {
            "username": "bobbyG",
            "name": "Bobby G",
            "avatar_url": "https://images.unsplash.com/photo-1500648767791-00dcc994a43e?q=80&w=1587&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
          },
          {
            "username": "code-master",
            "name": "Code Master",
            "avatar_url": "https://images.unsplash.com/photo-1511376777868-611b54f68947?q=80&w=1740&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
          }
        ]
      }
    }
  },
  "GET /api/users/:username": {
    "description": "Retrieves a user object by the given username",
    "details": {
      "queries": [],
      "exampleResponse": {
        "user": {
          "username": "butter_bridge",
          "avatar_url": "https://images.unsplash.com/photo-1500648767791-00dcc994a43e?q=80&w=1587&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
          "name": "jonny"
        }
      },
      "errorResponses": {
        "404": {
          "description": "User not found for the given username",
          "exampleResponse": {
            "msg": "404 - Not Found: User not found"
          }
        }
      }
    }
  }
}