Personal API - Weekend Lab

It's time to have some fun and play with the technologies you've learned in the past week. Your goal is to start your own API.

Your API can be related to whatever you like, but its Mongo DB must have at least 2 schemas/models that are connected by reference.

For example, if your API is for keeping track of various hotels, it would need to reference another type of object besides hotels. You might choose to provide more information about the cities your hotels are found in beyond a simple string like "Austin" or "Orlando". Your City schema/model could contain information about the city iself like city name, state, local attractions, and of course a list of related hotels connected by reference.

Your API should have:

• Well-organized JSON API Endpoints
• The ability to read (GET) each type of resource as a collection
• The ability to read (GET) each type of resource by specific ID
• The ability to create (POST) a new resource of each type
• At least one update (PUT) endpoint
• At least one delete (DELETE) endpoint

Try to start by completing the schema/model and implementing endpoints for only one type of resource and expand from there to include other schemas/models/endpoints.

Fork and clone this repo. You can use the placeholder code in this repo as a starting point.

Step 0: Deploy to Heroku

Before we start coding, let's prepare to deploy our API on Heroku so other developers can access our API from any computer.

You can find full instructions here: Deploying Express Apps to Heroku

As you continue to work on this project, you'll need to remember to push your changes to Heroku (just like you would with Github!):

# git add changed-files
# git commit -m "detailed description of what I changed"
git push heroku master
heroku open

It's common for code to break "in production" even when it works fine "in development" on your computer (due to different environment variables, missing dependenies, etc). Do your best to debug! Let us know if you get stuck on deployment issues.

Step 1: Verify the Test Routes in Postman

Since we're building a JSON API with no front-end (yet), Postman will come in handy for testing our work.

Make sure you've installed dependencies and added a .env file with your Mongo DB credentials. Then run the server with the placeholder code.

Use Postman to verify that the GET /test and POST /test endpoints work, confirming that our server can connect to our Mongo DB and complete operations on demand. For the POST endpoint, you can simply submit an object with a name property, and then it should appear in your next GET /test request:

{
    "name": "test item 1"
}

Step 2: Build Your Main Schema/Model

Next, go to the models/ folder and add a new file for your main schema/model. For now we'll create it without a reference to any other schemas/models.

Be sure to export the model from the file and then modify models/index.js. It should require the file you just created and then export the models from it so they can be used more directly while preparing responses for our routes.

Step 3: Create Your Primary Endpoints

Now go to the routes/ folder and create a new file to handle your endpoints for the primary model. It should contain function definitions for handling various endpoints (GET, POST, etc) related to your primary model.

Start with the GET method for retrieving all matching resources. Then add a function for adding new resources (POST). Then add a function for retireving a specific resource by ID (GET, with path parameter).

Make sure that for each function, you modify server.js to register the functions as endpoint/route handlers.

Step 4: Check Your Work in Postman

Open up Postman with your new code running on localhost. Hit your new GET and POST endpoints a few times to verify everything is working as expected.

If it's all working, add/commit your changes to git. Push to Github to backup your code. Push to Heroku so other people can use your newly created endpoints.

Return to Postman and test again, making sure that your code is working "in production" on the URL Heroku provided for your API server.

Step 5: Add Your Other Schemas/Models/Endpoints

Now it's time to expand on what you've done. Piece by piece, add the other schemas/models and endpoints you planned.

Be sure to test your endpoints as you go in Postman. Also don't forget to commit your changes and deploy to Heroku from time to time.

Options for Extra Challenge

• Add even more schemas/models/enpoints. Thinking of more detailed information is usually fairly easy, but the code to support it gets more difficult the more detail is added.
• Add support for query parameters to limit/filter responses on your endpoints that retrieve all resources in a collection. For example, you might limit items based on rating, time/date range, tags, etc.
• Document all the endpoints of your API in a markdown file. What does each endpoint do? How should a new user of your API get started?

Step 6: Add A README.md

A README is a consumer's first -- and maybe only -- look into your creation. The README is important for users to understand what it is they're looking at and how to use the code. It's up to the creator to prove that their work is a shining gem.

For your custom API, please create a README that details the following:

1. Description of what the API does
2. URL as deployed on Heroku
3. Maps out the API endpoints (method + path combos)
   • brief description of each endpoint
   • what's the expected response
   • any relevant options (i.e.query string options)
4. Provides a basic model structure
   • includes properties of each model
   • requirements for creation

Here is a curated list of AWESOME READMEs for inspiration.