API for Assignments 3.1 and 3.2

General Notes

• All endpoints return JSON. The response will always be an object (so e.g. if an endpoint returns an array, it will be wrapped in an object with a single key/value pair).
• When the endpoint returns an error status, the response body will be an object with an error key, whose value is a human-readable error message.
• In the examples, lines that begin with > are the request, and lines with no prefix are the response.
• Unless stated explicitly, elements in an array or key/value pairs in an object are in no particular order.

GET /

An endpoint to confirm the API is running. You won't have to use it, but it may be useful for testing. For assignment 3.2, it is already implemented.

Returns: An object with basic info about the database.

Example:

> GET /
Status: 200

{
  "db": "cs193x_mchang91",
  "numUsers": 1,
  "numPosts": 1
}

GET /users

Get a list of existing users.

Returns: An object with a single key, users, mapping to an array of user IDs.

Example:

> GET /users
Status: 200

{
  "users": [
    "mchang",
    "kashif"
  ]
}

GET /users/:id

Get the profile for the user id.

Returns: An object with the keys id, name, avatarURL (which are all strings), and following (which is an array of user IDs the given user is following).

Errors:

• 404 if the user does not exist

Examples:

> GET /users/mchang
Status: 200

{
  "id": "mchang",
  "name": "Michael",
  "avatarURL": "images/stanford.png",
  "following": [
    "kashif"
  ]
}

> GET /users/nobody
Status: 404

{
  "error": "No user with ID nobody"
}

POST /users

Create a new user. The new user's name is the same as their ID, their avatar URL is the default avatar (images/default.png), and they are not following anyone.

Request body: An object with a single key id, whose value is the new user's ID.

Returns: Same as GET /users/:id after user is created.

Errors:

• 400 if the request body is missing an id property, or the id is empty
• 400 if the user already exists

Example:

> POST /users
> {"id":"binky"}
Status: 200

{
  "id": "binky",
  "name": "binky",
  "avatarURL": "images/default.png",
  "following": []
}

PATCH /users/:id

Update a user's profile (name or avatar URL). User IDs cannot be changed, but including the id in the request body is allowed.

If the specified display name is the empty string, the user's display name is reset to their user ID. If the specified avatar URL is the empty string, the user's avatar is reset to the default avatar (images/default.png).

Request body: An object with any number of the keys id (ignored), name, and avatarURL.

Note: Explicitly sending an empty string for name/avatarURL will set them to their defaults; not including them at all will leave them unchanged.

Returns: Same as GET /users/:id after user is updated.

Errors:

• 404 if the user does not exist

Note: For assignment 3.1, our API checks if extra keys are included in the request body and returns an error if so. For assignment 3.2, you do not have to check for this case.

Example:

> PATCH /users/mchang
> {"name":"Michael Chang"}
Status: 200

{
  "id": "mchang",
  "name": "Michael Chang",
  "avatarURL": "images/stanford.png",
  "following": [
    "kashif"
  ]
}

GET /users/:id/feed

Get a user's feed. This includes posts from all users they are following, as well as their own. Posts are sorted in reverse chronological order (newest first).

Returns: An object with a single key posts, mapping to an array. Each element has the following structure:

{
  "user": {
    "id": <the poster's user ID>,
    "name": <the poster's display name>,
    "avatarURL": <the poster's avatar URL>
  },
  "time": <the date and time the post was made>,
  "text": <the post text>
}

Errors:

• 404 if the user does not exist

Example:

> GET /users/mchang/feed
Status: 200

{
  "posts": [
    {
      "user": {
        "id": "kashif",
        "name": "kashif",
        "avatarURL": "images/default.png"
      },
      "time": "2022-02-08T02:51:12.431Z",
      "text": "My new post"
    },
    {
      "user": {
        "id": "mchang",
        "name": "Michael Chang",
        "avatarURL": "images/stanford.png"
      },
      "time": "2022-02-07T19:32:52.063Z",
      "text": "Welcome to the Generic Social Media App!"
    }
  ]
}

POST /users/:id/posts

Create a new post by the given user. The post time is set to the current date/time.

Request body: An object with a single key text, containing the post text.

Returns: The exact object { "success": true }.

Errors:

• 404 if the user does not exist
• 400 if the request body is missing a text property, or the text is empty

Example:

> POST /users/kashif/posts
> {"text":"My new post"}
Status: 200

{
  "success": true
}

POST /users/:id/follow

Have the user id follow the target user.

Query string: target: the ID of the user to follow

Returns: The exact object { "success": true }.

Errors:

• 404 if either user id or target does not exist
• 400 if the query string is missing a target property, or the target is empty
• 400 if the user is already following the target
• 400 if the requesting user is the same as the target

Examples:

> POST /users/mchang/follow?target=binky
Status: 200

{
  "success": true
}

> POST /users/mchang/follow?target=kashif
Status: 400

{
  "error": "mchang is already following kashif"
}

DELETE /users/:id/follow

Have the user id stop following the target user.

Query string: target: the ID of the user to stop following

Returns: The exact object { "success": true }.

Errors:

• 404 if the user id does not exist
• 400 if the query string is missing a target property, or the target is empty
• 400 if the target user isn't being followed by the requesting user

Example:

> DELETE /users/mchang/follow?target=kashif
Status: 200

{
  "success": true
}