# API Specification

Values wrapped in `< >` are placeholders for what the field values should be. Also be sure to read the request route carefully when you implement it - typos WILL cause test cases to fail!

{% hint style="danger" %}
**NOTE ABOUT ERROR RESPONSES**
{% endhint %}

The server should return an error response for:

* `POST` requests, if the user does not supply one of the fields in the body (e.g. title, link, username, text, etc.) with a status code of 400 (bad request)
* Any request if the id in the URL does not exist, with a status code of 404 (not found)

{% code title="Error Response" %}

```javascript
{
   "error": "Your error message here"
}
```

{% endcode %}

For each of the following routes, we will specify a success response that you must implement, but make sure to also implement error responses accordingly!

## Expected Functionality

### Get all posts

**`GET`**`/api/posts/`

{% code title="Success Response" %}

```javascript
<HTTP STATUS CODE 200>
{
  "posts": [
    {
      "id": 0,
      "upvotes": 1,
      "title": "My cat is the cutest!",
      "link": "https://i.imgur.com/jseZqNK.jpg",
      "username": "alicia98"
    },
    {
      "id": 1,
      "upvotes": 3,
      "title": "Cat loaf",
      "link": "https://i.imgur.com/TJ46wX4.jpg",
      "username": "alicia98"
    },
    ...
  ]
}
```

{% endcode %}

### Create a post

**`POST`**`/api/posts/`

{% code title="Request" %}

```javascript
{
  "title": "I love my dog!",
  "link": "https://i.imgur.com/XsaLqi1.jpg",
  "username": "raahi014"
}
```

{% endcode %}

{% code title="Success Response" %}

```javascript
<HTTP STATUS CODE 201>
{
  "id": <Incremented ID>,
  "upvotes": 1,
  "title": "I love my dog!",
  "link": "https://i.imgur.com/XsaLqi1.jpg",
  "username": "raahi014"
}
```

{% endcode %}

### Get a specific post

**`GET`**`/api/posts/{id}/`

{% code title="Success Response" %}

```javascript
<HTTP STATUS CODE 200>
{
  "id": <ID>,
  "upvotes": <STORED UPVOTES OF POST WITH ID {id}>,
  "title": <STORED TITLE OF POST WITH ID {id}>,
  "link": <STORED LINK OF POST WITH ID {id}>,
  "username": <STORED USERNAME OF POST WITH ID {id}>
}
```

{% endcode %}

### Delete a specific post

**`DELETE`**`/api/posts/{id}/`

{% code title="Success Response" %}

```javascript
<HTTP STATUS CODE 200>
{
  "id": <ID>,
  "upvotes": <STORED UPVOTES OF DELETED POST WITH ID {id}>,
  "title": <STORED TITLE OF DELETED POST WITH ID {id}>,
  "link": <STORED LINK OF DELETED POST WITH ID {id}>,
  "username": <STORED USERNAME OF DELETED POST WITH ID {id}>
}
```

{% endcode %}

### Get comments for a specific post

**`GET`**`/api/posts/{id}/comments/`

{% code title="Success Response" %}

```javascript
<HTTP STATUS CODE 200>
{
  "comments": [
    {
      "id": 0,
      "upvotes": 8,
      "text": "Wow, my first Reddit gold!",
      "username": "alicia98"
    },
    ...
  ]
}
```

{% endcode %}

### Post a comment for a specific post

**`POST`**`/api/posts/{id}/comments/`

Note: comments should have **globally** unique IDs! That is, if a comment on one post has ID 5, no other comments, *even on other posts* should have an ID of 5!

{% code title="Request" %}

```javascript
{
  "text": "what a cute puppy aww",
  "username": "raahi014"
}
```

{% endcode %}

{% code title="Success Response" %}

```javascript
<HTTP STATUS CODE 201>
{
  "id": <COMMENT ID>,
  "upvotes": 1,
  "text": "what a cute puppy aww",
  "username": "raahi014"
}
```

{% endcode %}

### Edit a comment for a specific post

**`POST`**`/api/posts/{pid}/comments/{cid}/`

{% code title="Request" %}

```javascript
{
  "text": "what a cute puppy aww (edit): omg ty for the likes"
}
```

{% endcode %}

{% code title="Success Response" %}

```javascript
<HTTP STATUS CODE 200>
{
   "id": <CID>,
   "upvotes": <# UPVOTES>,
   "text": "what a cute puppy aww (edit): omg ty for the likes",
   "username": <USERNAME>
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://backend-course.cornellappdev.com/chapters/routes/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.