Skip to content

Latest commit

 

History

History
369 lines (257 loc) · 5.55 KB

DOCUMENTATION.md

File metadata and controls

369 lines (257 loc) · 5.55 KB
Raw

API Documentation

The document gives a detailed information on how to set up the REST API for the "Person" resource. There's the set up instruction, request/response formats, sample API usage and known limitations/assumptions made. Furthermore, there's a link to a live interactive documentation.

Setup instruction to run locally

If you choose to fork before cloning the project be sure to use the link from your own repo to clone.

Clone the project

  git clone https://github.com/A3AJAGBE/person_api

Go to the project directory

  cd person_api

Create virtual environment

  python3 -m venv venv

Activate virtual environment

  source venv/bin/activate

Install dependencies

  pip install -r requirements.txt

Start the server

  uvicorn main:app --reload

Environment Variables

To run this project, you will need to create a .env file and add the environment variable to it.

DATABASE_URL

an example on how to set the variable

DATABASE_URL = "sqlite:///[INSERT DB NAME HERE].db"

API Reference

POST the data

POST /api
Parameter Type Description
name string Required

GET all the data

GET /

GET the data by id

GET /api/{user_id}
Parameter Type Description
id integer Required

GET the data by using name

GET /api?name=[INSERT HERE]
Parameter Type Description
name string Required

PUT the data by id

PUT /api/{user_id}
Parameter Type Description
id integer Required

DELETE the data by id

DELETE /api/{user_id}
Parameter Type Description
id integer Required

Request and Response Format

Create a person (POST)

Request Format
{
  "name": "joel d'souza"
}
Response Format (success 200)
{
  "name": "Joel D'Souza",
  "user_id": 1
}
Response Format (Bad Request - 400)
{
  "detail": "Name exist already"
}
Request Format
{
  "name": "JaneDoe-Smith!"
}
Response Format (Bad Request - 400)
{
  "detail": "Invalid name input"
}

Get a person by id (GET)

Response Format (success 200)
{
  "name": "Joel D'Souza",
  "user_id": 1
}
Response Format (Not Found - 404)
{
  "detail": "Person not found"
}

Get a person using name (GET)

Response Format (success 200)
{
  "name": "Joel D'Souza",
  "user_id": 1
}
Response Format (Not Found - 404)
{
  "detail": "Person not found"
}

Update a person (PUT)

Request Format
{
  "name": "darnarys fire"
}
Response Format (success 200)
{
  "name": "Darnarys Fire",
  "user_id": 1
}
Response Format (Bad Request - 400)
{
  "detail": "No change in the name"
}
Response Format (Bad Request - 400)
{
  "detail": "Name exist already"
}
Request Format
{
  "name": " DarnarysFire"
}
Response Format (Bad Request - 400)
{
  "detail": "Invalid name input"
}
Response Format (Not Found - 404)
{
  "detail": "Person not found"
}

Delete a person (DELETE)

Response Format (success 200)
"Person with id number: 1 was deleted."
Response Format (Not Found - 404)
{
  "detail": "Person with id number: 3, not found."
}

Sample API Usage

Create a person

import requests

api_url = "http://127.0.0.1:8000/api"

add_person = {
    "name": "jessica pier"
}

res = requests.post(api_url, json=add_person)
data = res.json()
print(data)

Read a person by id

import requests

api_url = "http://127.0.0.1:8000/api/19"

res = requests.get(api_url)
data = res.json()
print(data)

Read a person using name

import requests

api_url = "http://127.0.0.1:8000/api?name=jessica pier"

res = requests.get(api_url)
data = res.json()
print(data)

Update a person

import requests

api_url = "http://127.0.0.1:8000/api/19"

update_person = {
    "name": "jess pier"
}

res = requests.put(api_url, json=update_person)
data = res.json()
print(data)

Delete a person

import requests

api_url = "http://127.0.0.1:8000/api/19"

res = requests.delete(api_url)
data = res.json()
print(data)

Running Tests

A test file "sql_test.py" has been created with tests to check. To run tests, run the following command

  pytest

More on documentation

Check out a live interactive documentation here. It will allow you interact/test the API with ease.

  • Go to the page
  • Click on the dropdown button on the right side corner of each requests (POST, GET, PUT, DELETE)
  • Click on "Try it now" button, it's on the right side corner as well
  • Fill the request body (if any)
  • click on "Execute"

Limitations/Assumptions

  • Familiarity with Python
  • Familiarity with git and GitHub
  • No auth Implementation for the API
  • The application was developed on MacOS
  • Knowledge of using the command line interface (CLI)