apiary.apib

FORMAT: 1A
HOST: https://hack-or-snooze-v3.herokuapp.com

# Hack or Snooze API

This API is similar to HackerNews. This is a RESTful JSON API with two key resources: **users** and **stories**.
All endpoints require authentication using JSON Web Tokens (JWT), with the exception of reading stories and creating users, which are open to the public.

 

---

## Quickstart

 

#### 1. First, make a cURL GET request to get an array of stories.

No authentication is required for this endpoint.

 

**Request**

`curl -i https://hack-or-snooze-v3.herokuapp.com/stories`

**Response**

```
{
  "stories": [
    {
      "author": "Elie Schoppik",
      "createdAt": "2018-11-14T01:36:12.710Z",
      "storyId": "991b95a0-507f-472e-9f94-e3bd4b6fe882",
      "title": "Four Tips for Moving Faster as a Developer",
      "updatedAt": "2018-11-14T01:36:12.710Z",
      "url": "https://www.rithmschool.com/blog/developer-productivity",
      "username": "test"
    }
  ]
}
```

 

#### 2. Next, let's sign up and get a token.

 

**Request**

This is a [POST request to /signup](/#reference/0/signup).

```
curl -i \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"user":{"name":"Test User","username":"test","password":"foo"}}' \
      https://hack-or-snooze-v3.herokuapp.com/signup
```

**Response**

```
{
  "token": "YOUR_TOKEN_SHOWS_UP_HERE",
  "user": {
    "createdAt": "2018-11-14T01:35:07.974Z",
    "favorites": [],
    "name": "Test User",
    "stories": [],
    "updatedAt": "2018-11-14T01:35:07.974Z",
    "username": "test"
  }
}
```

We will include the `token` for future requests that require authentication.

 

#### 3. Create a New Story

Using the token, make a POST request to `/stories`.

 

For all future requests, the token can be placed either:

- in the query string (for `GET` requests, e.g. `/users/test?token=eyfasf...`)
- or in the request body (for `POST` and `PATCH` requests, e.g. `"token": "eyfasf"`)

 

**Request**

For this request, we will place the token in the body, since it is a [POST request to /stories](/#reference/0/stories).

```
curl -i \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"token":"PASTE_YOUR_TOKEN_HERE", "story": {"author":"Elie Schoppik","title":"Four Tips for Moving Faster as a Developer", "url": "https://www.rithmschool.com/blog/developer-productivity"} }' \
      https://hack-or-snooze-v3.herokuapp.com/stories
```

**Response**

```
{
  "story": {
    "author": "Elie Schoppik",
    "createdAt": "2018-11-14T01:36:12.710Z",
    "storyId": "991b95a0-507f-472e-9f94-e3bd4b6fe882",
    "title": "Four Tips for Moving Faster as a Developer",
    "updatedAt": "2018-11-14T01:36:12.710Z",
    "url": "https://www.rithmschool.com/blog/developer-productivity",
    "username": "test"
  }
}
```

 

See the [Reference section](/#reference/0/auth) below for fully-detailed resource documentation, including which routes are protected.

---

## Resource Structure

### Collections

The API provides access to the following collections.
Both collections have full CRUD (Create, Read, Update, Delete) operations.

#### Users

- Collection Endpoint: `/users`
- Singular Endpoint: `/users/{username}`
- Attributes:
  - name
  - username
  - password
  - stories (a list of stories that the user posted)
  - favorites (a list of stories that the user favorited)
- Token Required for all users endpoints.

#### Stories

- Collection Endpoint: `/stories`
- Singular Endpoint: `/stories/{storyId}`
- Attributes:
  - author
  - title
  - url
  - username (who the story was posted by)
  - storyId (autogenerated upon creating a story)
- Token Required for: `POST /stories`, `PATCH /stories/{storyId}`, `DELETE /stories/{storyId}`


**Posting a New Story**:

Send a `POST` request to `/stories` endpoint.

Example Payload:
```json
{
    "token": "YOUR_TOKEN_HERE",
    "story": {
        "author": "Matt Lane", 
        "title": "The best story ever",
        "url": "http://google.com"
    }
}
```

 


## Authentication

Many of the endpoints require a token to be accessed.

The token can be placed either:

- in the query string (for `GET` requests, e.g. `/users/test?token=eyfasf...`)
- or in the request body (for `POST` and `PATCH` requests, e.g. `"token": "eyfasf"`)

 

Here are endpoints that get you a token back:

- Signup Endpoint: `/signup` - when you want to create a new user and immediately get a token for them
- Login Endpoint: `/login` - when you want to get a token for a user that already exists

Login/Signup Payload Format:
```json
{
    "user": {
        "username": "test",
        "password": "password"
    }
}
```

See the [Reference section](/#reference/0/login) for fully-detailed resource documentation.

 

---

## Login [/login]
Endpoint for logging in to get a token and see your profile.

### Login to Receive a Token [POST]

+ Request
    + Attributes 
        + user (Login)
    + Body

            {
                "user": {
                    "username": "test",
                    "password": "password"
                }
            }

+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + token: `eyJhb...` (string, required) - JWT used to authenticate in the future.
        + user (User)

+ Response 400 (application/json; charset=utf-8)
    + Attributes
        + error (Bad Request)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)


## Signup [/signup]
Endpoint for creating an account and getting a token from the server.

### Signup and Get a Token [POST]

+ Request
    + Attributes
        + user (New User)
    + Body

            {
                "user": {
                    "name": "Test User",
                    "username": "test",
                    "password": "password"
                }
            }


+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + token: `eyJhbGciO...` (string, required) - JWT used to authenticate in the future.
        + user (User)

+ Response 400 (application/json; charset=utf-8)
    + Attributes
        + error (Bad Request)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)

## Users [/users{?skip,limit}]
Endpoint to create a user or query for a list of users.

+ Parameters
    + skip: 0 (number, optional) - the list of documents to skip over. Default is 0.
    + limit: 10 (number, optional) - the number of documents to return. Default and maximum set to 25.

### Get a List of Users [GET]
**Token Required**. Note: passwords are not visible at this endpoint. By default, `limit` is set to 25.
    
+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + users (array[User])

+ Response 400 (application/json; charset=utf-8)
    + Attributes
        + error (Bad Request)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)


## User [/users/{username}]
Endpoint for reading, updating, or deleting a single user. 

+ Parameters
    + username: hueter (string, required) - the username to lookup.

### Get a User [GET]
**Token Required**. Retrieve a single user document by `username`.

+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + user (User)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)


### Update a User [PATCH]
**Token Required. Correct User Required.** Update a single user document by `username`. Note: `username` and `favorites` are immutable via this endpoint.

+ Request
    + Attributes
        + user (New User)
    + Body

            {
                "token": "YOUR TOKEN GOES HERE",
                "user": {
                    "name": "A Changed Name"
                }
            }

+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + user (User)

+ Response 400 (application/json; charset=utf-8)
    + Attributes
        + error (Bad Request)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)

+ Response 403 (application/json; charset=utf-8)
    + Attributes
        + error (Forbidden)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)

### Delete a User [DELETE]
**Token Required. Correct User Required.** Remove a single user document by `username`.

+ Request
    + Attributes
        + token (string, required)
    + Body

            {
                "token": "YOUR TOKEN GOES HERE"
            }

+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + message: `User successfully deleted` (string, optional)
        + user (User)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)

+ Response 403 (application/json; charset=utf-8)
    + Attributes
        + error (Forbidden)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)


## User Favorites [/users/{username}/favorites/{storyId}]

+ Parameters
    + username: hueter (string, required) - the target user.
    + storyId: `32d336da-98cd-4010-bb39-1d789b9bef50` (string, required) - the story's ID for the target favorite.

### Add a New Favorite [POST]
**Token Required. Correct User Required.** Full user document will be returned. Note: password will not be present in the response. 
There is no request body necessary.

+ Request
    + Attributes
        + token (string, required)
    + Body

            {
                "token": "YOUR TOKEN GOES HERE"
            }
+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + message: `Favorite Added Successfully!` (string, optional)
        + user (User)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)

### Delete a User Favorite [DELETE]
**Token Required. Correct User Required.** Full user document will be returned. Note: password will not be present in the response. 
There is no request body necessary.

+ Request
    + Attributes
        + token (string, required)
    + Body

            {
                "token": "YOUR TOKEN GOES HERE"
            }
+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + message: `Favorite Deleted Successfully!` (string, optional)
        + user (User)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)


## Stories [/stories{?skip,limit}]
Endpoint to create a story or query for a list of stories.


### Get a List of Stories [GET]
By default, `limit` is set to 25.

+ Parameters
    + skip: 0 (number, optional) - the list of documents to skip over. Default is 0.
    + limit: 10 (number, optional) - the number of documents to return. Default and maximum set to 25.


+ Response 200 (application/json; charset=utf-8)
    + Attributes (array[Story])

+ Response 400 (application/json; charset=utf-8)
    + Attributes
        + error (Bad Request)

### Create a New Story [POST]
**Token Required**. The fields `username`, `title`, `author`, and `url` are required.

+ Request
    + Attributes 
        + story (New Story)
    + Attributes
        + token (string, required)
    + Body

            {
                "token": "YOUR_TOKEN_HERE",
                "story": {
                    "author": "Matt Lane",
                    "title": "The best story ever",
                    "url": "http://google.com"
                }
            }

+ Response 201 (application/json; charset=utf-8)
    + Attributes 
        + story (Story)

+ Response 400 (application/json; charset=utf-8)
    + Attributes
        + error (Bad Request)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)


## Story [/stories/{storyId}]
Endpoint for reading, updating, or deleting a single story. 

+ Parameters
    + storyId: `7df55f38-2611-48c2-b01f-6a4e38f80855` (string, required) - the story ID to lookup.

### Get a Story [GET]
Retrieve a single story document by `storyId`.

+ Response 200 (application/json; charset=utf-8)
    + Attributes 
        + story (Story)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)


### Update a Story [PATCH]
**Token Required. Correct User Required.** Update a single story document by `storyId`. Note: `username` is immutable at this endpoint.

+ Request
    + Attributes 
        + token (string, required)
        + story (New Story)
    + Body

            {
                "token": "YOUR_TOKEN_HERE",
                "story": {
                    "author": "Not Matt Lane"
                }
            }

+ Response 200 (application/json; charset=utf-8)
    + Attributes 
        + story (Story)

+ Response 400 (application/json; charset=utf-8)
    + Attributes
        + error (Bad Request)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)

+ Response 403 (application/json; charset=utf-8)
    + Attributes
        + error (Forbidden)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)

### Delete a Story [DELETE]
**Token Required. Correct User Required.** Remove a single story document by `storyId`.

+ Request
    + Attributes
        + token (string, required)
    + Body

            {
                "token": "YOUR_TOKEN_HERE"
            }
+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + message: `Story deleted successfully` (string, optional)
        + story (Story)

+ Response 401 (application/json; charset=utf-8)
    + Attributes
        + error (Unauthorized)

+ Response 403 (application/json; charset=utf-8)
    + Attributes
        + error (Forbidden)

+ Response 404 (application/json; charset=utf-8)
    + Attributes
        + error (Not Found)


## Data Structures

### Login
  + username: `hueter` (string, optional) - username can only consist of letters and numbers between 1 and 55 characters. **Required to Login**
  + password: `foo123` (string, optional) - between 1 and 55 characters. **Required to Login.**

### New User
  + name: `Michael Hueter` (string, optional) - the user's full name, between 1 and 55 characters. 
  + password: `foo123` (string, optional) - between 1 and 55 characters. 
  + username: `hueter` (string, optional) - username can only consist of letters and numbers between 1 and 55 characters. **Immutable.**

### User
  + createdAt: `017-11-09T18:38:39.409Z` (string, optional) - auto-generated timestamp of when the user was originally created.
  + favorites (array[Story], optional) - a list of stories that are the user's favorites
  + name: `Michael Hueter` (string, optional) - the user's full name, between 1 and 55 characters. 
  + password: `foo123` (string, optional) - between 1 and 55 characters. 
  + stories (array[Story], optional) - a list of stories that the user has published
  + updatedAt: `017-11-09T18:38:39.409Z`  (string, optional) - auto-generated timestamp of when the user was last updated.
  + username: `hueter` (string, optional) - username can only consist of letters and numbers between 1 and 55 characters. **Immutable.**

### Story
  + author: `Matt Lane` (string, optional) - the original author of the story. 
  + createdAt: `017-11-09T18:38:39.409Z`  (string, optional) - auto-generated timestamp of when the story was originally created.
  + storyId: `5081e46e-3143-4c0c-bbf4-c22eb11eb3f5` (string, optional) - the auto-generated ID of the story used to reference story documents in routes.
  + title: `The Best Story Ever` (string, optional) - the title of the story. 
  + updatedAt: `017-11-09T18:38:39.409Z`  (string, optional) - auto-generated timestamp of when the story was last updated.
  + url: `https://www.rithmschool.com/blog/do-web-developers-need-to-be-good-at-math` (string, optional) - the URL of the story. **Must Conform to URI Format.**
  + username: `hueter` (string, optional) - the user who posted the story. 

### New Story
  + author: `Matt Lane` (string, optional) - the original author of the story. 
  + title: `The Best Story Ever` (string, optional) - the title of the story. 
  + url: `https://www.rithmschool.com/blog/do-web-developers-need-to-be-good-at-math` (string, optional) - the URL of the story. **Must Conform to URI Format.**

### Bad Request
  + status: 400 (number, required) - HTTP status code
  + title: 'Bad Request' (string, required) - text accompanying the status code
  + message: 'Invalid schema format or malformed JSON.' (string, required) - description of the error

### Unauthorized
  + status: 401 (number, required) - HTTP status code
  + title: 'Unauthorized' (string, required) - text accompanying the status code
  + message: 'You need to authenticate before accessing this resource.' (string, required) - description of the error

### Forbidden
  + status: 403 (number, required) - HTTP status code
  + title: 'Forbidden' (string, required) - text accompanying the status code
  + message: 'You are not allowed to modify this resource.' (string, required) - description of the error

### Not Found
  + status: 404 (number, required) - HTTP status code
  + title: 'Not Found' (string, required) - text accompanying the status code
  + message: 'Document with that ID was not found.' (string, required) - description of the error

### Conflict
  + status: 409 (number, required) - HTTP status code
  + title: 'Conflict' (string, required) - text accompanying the status code
  + message: 'Another document with the same ID already exists.' (string, required) - description of the error

### Success
  + status: 200 (number, required) - HTTP status code
  + title: 'Success' (string, required) - text accompanying the status code
  + message: 'The operation was successful.' (string, required) - description of the event