> For the complete documentation index, see [llms.txt](https://backend-course.cornellappdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://backend-course.cornellappdev.com/chapters/routes/api.md).

# 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 %}