API for Assignments 3.1 and 3.2
Written by MichaelThis page describes the endpoints for the API you will use as a client in assignment 3.1 and implement in assignment 3.2.
GET /
GET /users
GET /users/:id
POST /users
PATCH /users/:id
GET /users/:id/feed
POST /users/:id/posts
POST /users/:id/follow
DELETE /users/:id/follow
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
ortarget
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
}